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Series Introduction 





This book is a part of a series of books designed to get programmers 
the information they need in a quick and efficient manner. 
Programmers don’t have time to hunt through huge unwieldy manu- 
als trying to find the little piece of information they need to finish 
their tasks. To that end, the design of these books has been optimized 
by programmers for programmers. 

All APIs have been organized into logical groups rather than al- 
phabetically, so, you will find all of the APIs relating to semaphores 
grouped together in one chapter, for example. The reasoning for this 
is clear: A programmer looking up how to create a semaphore will 
most likely want to know how to request it, release it, and so on, im- 
mediately afterward. | 

In addition to grouping related APIs, any information that relates 
to that group is provided in the same chapter. Each chapter is prefixed 
with a quick summary of the system architecture related to those APIs, 
and suffixed with any related structures. In some cases, other related 
information may be found in the back of the chapter as well. 

The architecture summaries at the beginning of the chapters are 
designed to provide the programmer a quick overview or, in some cases, 
a refresher on the topic in just a few minutes. I recommend that pro- 
grammers take the time to read these overviews before delving into de- 
sign and coding since so many problems arise from poor initial design 
resulting from a lack of knowledge of the architecture of the topic. 

The API pages were designed primarily for efficiency. Therefore, 
each book in this series may have some small differences on the pages 
containing the actual APIs. For example, the Workplace Shell reference 
does not contain any references to what “INCL_” to define for a given 
API since there is only one for the entire set of Workplace Shell APIs. 

It is my sincere hope that you will find the books in this series the 
quickest, most informative, best organized programmers’ reference 
books you have ever used. 


Marc Stock 


How to Use This Book 





This book is designed as a combination guide and reference, with the 
emphasis on reference. If you are not familiar with the architecture of 
a particular topic, I recommend that you read the architecture sum- 
maries found at the beginning of every chapter. They are short and to 
the point, but they can be very useful for improving your understand- 
ing of the “big picture” or as a quick refresher on an operating system 
feature you used long ago. The summaries also include a section that 
discusses related system limitations, warnings, and the list of APIs be- 
longing to that section. 

If you are familiar with a particular topic and just need to go toa 
specific API, the APIs can be found either by looking them up alpha- 
betically in the chapter to which they belong, or from the API index 
provided in the back. If you don’t know to which topic the API be- 
longs, go to the index. 

Each API includes a prototype of the call. The data types are in 
boldface to help guide the eye when trying to determine which types 
need to be passed. In the parameters section of each call, the parame- 
ter name is shown in boldface/italics to aid in quick location of the pa- 
rameter you are looking for. Note: The prototypes shown in this book 
are for the C interfaces that are included with the OS/2 Toolkit. If you 
are using C++, you will find that a few of the parameter types are a lit- 
tle different from the ones shown in this reference. The Toolkit head- 
ers for C++ use a new type called PCSZ for pointers to null-terminated 
constants. 

Each API also includes an Other Info section which contains mis- 
cellaneous information needed for doing everything from determin- 
ing which #define is required to include the API’s prototype, to which 
DLL contains the code for that API. Here is an example of an Other 
Info section: 


OTHER INFO 
Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 257 DLL: DOSCALLS 
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The Include listed contains the function prototype for the call and 
any related #defines, structures, and more. Do not include this file at 
the beginning of your code. This information is provided purely for 
reference purposes. You will also find the name of the #define that 
should be included to cause the C preprocessor to pull in the neces- 
sary function prototypes and #defines so that the compiler will not 
complain. 

Each API also includes a See Also section that includes the names 
of related APIs that might be of interest. 


Table of Contents 





Chapter | 


Chapter 2 


Chapter 3 


Chapter 4 


Chapter 5 


Chapter 6 


Chapter 7 


Chapter 8 


Series Introduction 

How to Use this Book 

Introduction 

PM Application Setup and Cleanup 
Error Processing 

Setup and Cleanup Functions 
Registering and Creating Windows 
The Standard Window 

Register and Create Window Functions 
Messaging 

Posted vs. Sent Messages 

Messaging Functions 

Keystrokes and Focus 

Active Window vs. Focus Window 
Focus Change Sequence 

Virtual Keys 

Keystrokes and Focus Functions 
Presentation Spaces and Device Contexts 
Presentation Space Types 

Presentation Space and Device Context Functions 
Window Drawing Functions 
Window Drawing Functions 

Clipping and Invalid Regions 

The Invalid Region and the WM_PAINT Message 
Clipping and Invalid Region Functions 
Menus 

Creating a Menu 

Menu Window Styles 

Menu Item Styles 

Menu Item Attributes 

Menu Functions 


Vil 
Xi 


I3 
14 
14 
32 
33 
33 


79 

79 

80 

80 
103 
104 
104 
114 
114 
135 
136 
136 
[50 
IS] 
[51 
152 
153 
153 


1X 


x OS/2 WARP Presentation Manager API 


Chapter 9 


Chapter 10 


Chapter I | 
Chapter |[2 


Chapter |3 


Chapter 14 


Chapter I|5 


Chapter 16 


Chapter |7 


Chapter 18 


Chapter 19 


Chapter 20 


Appendix A 
Appendix B 


Dialogs 

Modal and Modeless Dialogs 

Dialog Coordinates 

Dialog Functions 

Standard Dialogs 

Customizing the Dialogs 

Standard Dialog Functions 

Resources 

Resource Functions 

Help 

Help Functions 

Window Information 

System-Defined Information vs. 
Application-Defined 

Presentation Parameters 

Window Information Functions 

System Information 

System Information Functions 

Atoms 

Atom Functions 

The Clipboard and Dynamic 

Data Exchange 

Clipboard Formats 

Clipboard and DDE Functions 

Rectangles 

What Is a Rectangle? 

Rectangle Functions 

Task List Functions 

OS/2 |. Compatibility 

Task List Functions 

Workplace Shell Functions 

Workplace Shell Object Classes 

Setup Strings and Object IDs 

Workplace Shell Functions 

National Language Support 

Code Pages 

Country Codes 

NLS Functions 

WinLockVisRegions 

Alphabetical Function List 

Index 


166 
166 
167 
167 
204 
204 
207 
226 
227 
260 
260 
270 


270 
LF 
2i2 
325 
325 
357 
358 


368 
369 
370 
388 
388 
389 
401 
40 
402 
426 
427 
427 
428 
452 
453 
453 
455 
467 
468 
475 


Introduction 





OS/2 Warp Version 3 Presentation Manager API describes the user-inter- 
face functions available to Presentation Manager programs. The docu- 
mentation for each function lists the function’s arguments and return 
value, its header file, related functions, and remarks about this func- 
tion. 

This book is designed to be concise, complete, and easy to read. 
Each function is cross-referenced with related functions’ page num- 
bers, making it simple to code sequences of functions. If a function re- 
quires a data structure, in most cases, the structure’s description is on 
the same page as the function, so you don’t have to page through the 
book. The error return values for each function are documented by 
symbolic name and value, again saving you from looking for them. 
Many of the functions have a real-world, working sample program list- 
ing that illustrates how to use the function in an actual application. 


Using This Book 


This book is divided into chapters, each of which documents a cate- 
gory of the Presentation Manager functions. We have grouped the 
functions to minimize the amount of page flipping required; for ex- 
ample, all of the functions for Help Manager are near each other. At 
the beginning of each chapter, there is a description of the category 
followed by a list of the functions described in that category. 

In addition, because sometimes you just need to look for a specific 
function, that’s where the alphabetical function listing, found in 
Appendix B, comes in handy. This listing lets you quickly turn to the 
function you are interested in. 


PM Header Files 


The Presentation Manager functions are defined in header files that 
come with your PM toolset. In this book, each function’s description 
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lists the function’s header file, so you can examine the function's ac- 
tual definition. Most C or C+ programs include the header files like: 


#define INCL _PM 
# <os2.h> 


The #define INCL_PM statement defines a symbol that the header 
files use for conditional compilation. This particular symbol causes the 
compiler to define all of the functions and symbols required for any 
type of Presentation Manager programming. You can, if you wish, be 
more specific, and include only the symbols and functions required by 
your program. In this book, each function’s description lists another 
symbol that you could define before including OS2.H This symbol 
(such as INCL_WINWINDOWMGR) includes the smallest increment of 
the header file required for the given function. 

The OS2.H header file includes several other header files. The fol- 
lowing are germane to this book: 


PMWIN.H_ Defines the majority of the symbols, constants, structures, 
and functions for Presentation Manager programming. Anything 
not mentioned in the rest of the header files is defined here. 

PMERR.H Defines symbolic names and values for the error codes 
generated by Presentation Manager programs. You can obtain the 
error code from a function at runtime by calling WinGetLastError 
(pg 9) or WinGetErrorInfo (pg 6). 

PMSHL.H Defines symbols, constants, structures, and functions for 
manipulating the ‘Task List. 

PMHELP.H Defines symbols, constants, structures, and functions for 
programming the Information Presentation Facility (Help Manager). 

PMWP.H_ Defines symbols, constants, structures, and functions for 
programming the Workplace Shell. 

PMSTDDLG.H Defines symbols, constants, structures, and functions 
for programming the Font and File standard dialog. 





PM Application 
Setup and 
eanup 





Bo: a Presentation Manager (PM) program can display a window 
or dialog, it needs to execute at least some of the system calls in this 
section. In addition, the program needs to call other functions upon 
termination to free resources. The flow for a typical PM program is: 


WinInitialize 
WinCreateMsgQueue 
WinRegisterClass 
WinCreateStdwindow 
while ( WinGetMsg ) 
WinDispatchMsg 
WinDestroyWindow 
WinDestroyMsgQueue 


WinTerminate 
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Error Processing 


Most Presentation Manager functions return an indication if the call 
was successful. If the call failed, the program can query the anchor 
block to retrieve information about the error, including an error code. 
PM provides the WinGetErrorInfo (pg 6), and WinGetLastError (pg 9) 
functions to retrieve the error information. 


Setup and Cleanup Functions 





WinCancelShutdown prevents a background thread from receiving 
WM_QUIT messages (pg 2). 

WinCreateMsgQueue creates the message queue required by all PM 
programs (pg 3). 

WinDefWindowProc processes messages for a window procedure 
(pg 4). 

WinDestroyMsgQueue destroys the message queue (pg 5). 
WinGetErrorInfo retrieves an error information structure (pg 6). 
WinGetLastError retrieves an error code (pg 9). 

WinFreeErrorInfo deallocates an error information structure (pg 10). 
WinInitialize creates the anchor block data structure required by all 
PM programs and certain background threads (pg 10). 
WinQueryAnchorBlock retrieves the current anchor block handle 
(pg 11). 

WinTerminate destroys the anchor block data structure (pg 12). 





@ WinCancelShutdown 


Processes a WM_QUIT message or prevents a thread from receiving the 
WM_QUIT message. 


SYNTAX 
BOOL WinCancelShutdown (HMQ hmq, BOOL /fCancelAlways) 
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PARAMETERS 

hmgq - input 

The message queue handle for the current thread. 

fCancelAlways - input 

Pass TRUE to indicate that the thread shouldn’t receive the WM_QUIT 
message upon system shutdown. Pass FALSE to inform PM that the 
thread will ignore the WM_QUIT message, but wishes to see any subse- 
quent WM_QUIT messages. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
DosCreateMsgQueue -3 


NOTES 


When the system is shut down, the Workplace Shell posts a WM_QUIT 
message to all message queues and then waits for the application to ei- 
ther destroy its message queue or issue this function. If you create a 
background thread that creates a message queue but doesn’t read it, 
then you should issue this function with a TRUE argument during the 
thread’s initialization. 





WinCreateMsgQueue 


Creates a message queue. 


SYNTAX 
HMQ WinCreateMsgQueue (HAB hab, LONG /Eniries) 


PARAMETERS 

hab - input 

The current thread’s anchor block handle created by WinInitialize or 
retrieved with WinQueryAnchorBlock. 

lEntries - input 
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The maximum number of messages that can reside in the queue. Pass 
zero to use the system-defined maximum, or a maximum entry count 
value. 


RETURNS 


NULLHANDLE - The queue cannot be created. 
Other - message queue handle 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinDestroyMsgQueue -5, WinInitialize -10 


NOTES 


Many Presentation Manager calls require the existence of a message 
queue; for example, WinSendMessage. Therefore, you must issue Win- 
CreateMsgQueue on any thread that will issue WinSendMessage. 

There must be a valid anchor block created on the thread before 
you issue this call. 





@ WinDefWindowProc 





Processes messages for a window procedure. 


SYNTAX 


MRESULT WinDefWindowProc (HWND hwnd, ULONG msgid, 
MPARAM mp1, MPARAM mp2) 


PARAMETERS 

hwnd - input 

The window’s handle. 

msgid - input 

The message identifier. 

mpI - input 

The first message parameter. 
mp2 - input 

The second message parameter. 
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RETURNS 


The message result. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinDefDlgProc -172 


NOTES 

A window procedure can pass unprocessed messages to this function 
for default handling. In other words, this function provides the default 
behavior for window procedures. 





WinDestroyMsgQueue 


Destroys a thread’s message queue. 


SYNTAX 
BOOL WinDestroyMsgQueue (HMQ hig) 


PARAMETERS 
hmgq - input 
The handle of the message queue to destroy. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1002 PMERR_INVALID_HMQO 


SEE ALSO 
WinCreateMsgQueue -3 


NOTES 
Only the thread that created the message queue should destroy it. 
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WinGetErrorlnfo 


Retrieves an error information structure. 


SYNTAX 
PERR@RINFO WinGetErrorInfo (HAB hab) 


PARAMETERS 

hab - input 

The current thread’s anchor block handle created by WinInitialize or 
retrieved with WinQueryAnchorBlock. 


RETURNS 
A pointer to an ERRG&INFO structure: 


typedef struct _EBRINFO /* erri */ 
3 

ULONG cbFixedErriInfo; 
ERRORID idError; 
ULONG cDetailLevel; 
ULONG offaoffszMsg; 
ULONG offBinaryData; 

} ERRINFO; 


cbFixedErrInfo The size of the fixed portion of the structure, in bytes. 

idError This is the same value returned by WinGetLastError. A 32-bit 
value containing a severity code in the most significant 16 bits and 
an error code in the least significant 16 bits. You can use the macros 
ERRORIDSEV and ERRORIDERROR defined in OS2DEF.H to extract 
the severity and error codes. The values for severity are: 


SEVERITY _NOERROR 
SEVERITY_WARNING 
SEVERITY_ERROR 

SEVERITY SEVERE 

SEVERITY _UNRECOVERABLE 


The Presentation Manager error codes are listed in PMERR.H. 

cDetailLevel The number of entries in the array of messages that fol- 
lows. Currently, this is one. 

offaoffszMsg A table containing 32-bit offsets from the start of the er- 
ror information structure. There are cDetailLevel entries in this table. 
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Each entry in the table contains an offset of an error message string. 
The first message string contains the most detail. 

offBinaryData Some errors report information in addition to the mes- 
sage string. This field contains the offset of this information from 
the start of the error information structure. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINERRORS 


SEE ALSO 
WinFreeErrorInfo -10, WinGetLastError -9 


NOTES 
You should free the error information structure after you are finished 
with it. 

You should not query the error information structure unless a 
function reports that an error has occurred. 


EXAMPLE 


This function queries the error information aand displays its contents 
in a message box: 


void disperr ( HAB hab ) 
{ 


PSZ pszMsg; // error message string 

CHAR sz( 20]; // temp string 

PBYTE pb; // points to err message 

PBYTE p; // temp pointer 

PERRINFO perr; // return from WinGetErroriInfo 
ULONG 1dErr; // error identifier 

PSZ pszSev; // severity string 

PULONG pul; // points to offset table 
ULONG uls // entry from offset table 


// allocate memory for an error message string 
pszMsg = (PSZ)malloc ( 1000 ); 
// retrieve a structure containing error info 
// from the anchor block 
perr = WinGetErroriInfo ( hab ); 
if ( perr != NULL ) 
{ 
// point to the error message string in the structure 


// and copy to the message string 
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pul = (PULONG) ( (PBYTE)perr + perr->offaoffszMsg ); 
ul = “pul; 
pb = (PBYTE)perr + ul; 


// strip off any ending \n 
pO = stranr ( pb, "wm" y; 
if ( p != NULL ) 
= (ply, = *\0% 9 
strcpy ( pszMsg, “Error msg: ” ); 
strcat ( pszMsg, pb ); 


// next, the error ID 


i1dErr = ERRORIDERROR ( perr->idError ); 


_itea { idErr, sz, 16 }, 
strceat ( pszMsg, “, Error code: 0x” 
streat ( pszgMsg, sz ); 


// finally, the error severity code 


Switch ( ERRORIDSEV ( perr->idError ) 


{ 
case SEVERITY_NOERROR: 
pszSev = “No error”; 
break; 


case SEVERITY_WARNING: 


pszSev = “Warning”; 
break; 

case SEVERITY_ERROR: 
pSszsev = “Error”; 
break; 

case SEVERITY_SEVERE: 
pszSev = “Severe”; 
break; 

case SEVERITY_UNRECOVERABLE: 
pszSev = “Unrecoverable”; 
break; 

} 

strceat ( pszMsg, “, Error severity: 


strcat ( pszMsg, pszSev ); 


// display the error and clean up 


WinMessageBox ( HWND_DESKTOP, HWND_DESKTOP, pszMsg 


,» “Function Error! ” 


, O, MB_OK | MB_ERROR | MB_MOVEABLE 


free ( pszMsg ); 


WinFreeErrorinfo ( perr ); 
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@ WinGetLastError 


Retrieves an error code. 


SYNTAX 
ERRORID WinGetLastError(HAB hab) 


PARAMETERS 

hab - input 

The current thread’s anchor block handle created by WinInitialize or 
retrieved with WinQueryAnchorBlock. 


RETURNS 


A 32-bit value containing a severity code in the most significant 16 bits 
and an error code in the least significant 16 bits. You can use the 
macros ERRORIDSEV and ERRORIDERROR defined in OS2DEF.H to 
extract the severity and error codes. The values for seventy are: 


SEVERITY _NOERROR 
SEVERITY_WARNING 
SEVERITY_ERROR 

SEVERITY _SEVERE 
SEVERITY _UNRECOVERABLE 


The Presentation Manager error codes are listed in PMERR.H. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINERRORS 


SEE ALSO 
WinGetErrorInfo -6 


NOTES 


You should not query the error unless a function reports that an error 
has occurred. 

The ERRORIDERROR and ERRORIDSEV macros return 16-bit val- 
ues given the error ID: 


ERRORID eid = WinGetLastError ( hab ); 
USHORT usSev = ERROROIDSEV ( eid ); 
USHORT usCode = ERRORIDERROR ( eid ); 
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@ WinFreeErrorInfo 





Deallocates an error information structure. 


SYNTAX 
BOOL WinFreeErrorInfo (PERRORINFO pez) 


PARAMETERS 

pet - input 

A pointer to an error information structure allocated by WinGet- 
ErrorInfo. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINERRORS 


SEE ALSO 
WinGetErrorInfo -6 





@ Winlnitialize 





Creates an anchor block structure assigned to the calling thread. 


SYNTAX 
HAB WinInitialize (ULONG /lOpizons) 


PARAMETERS 
flOptions - input 


Reserved: set to zero. 


RETURNS 
The anchor block handle if successful, or NULLHANDLE. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDOWMGR 
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SEE ALSO 


Win Terminate -12, WinQueryAnchorBlock -11, WinGetLastError -9, 
WinGetErrorInfo -6 


NOTES 


When a thread issues this function, PM allocates an internal data struc- 
ture called an anchor block which holds error information. If a PM 
function reports an error, a program can retrieve error information 
with WinGetLastError or WinGetErrorInfo. 

Many PM functions (including GPI functions) require the exis- 
tence of an anchor block on the calling thread. Therefore, any thread 
that will call PM or GPI functions should issue WinInitialize before 
calling those functions. 

A thread can only issue this function once—internally, PM associ- 
ates the anchor block handle with the thread. 





WinQueryAnchorBlock 


Retrieves the anchor block handle for a window. 


SYNTAX 
HAB WinQueryAnchorBlock (HWND hwnd) 


PARAMETERS 
hwnd - input 
The window for which to retrieve the anchor block handle. 


RETURNS 
The anchor block handle if successful, or NULLHANDLE. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinInitialize -10, WinTerminate -12 


NOTES 
Although it’s not documented by IBM, you can retrieve the anchor 
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block handle for the current window by passing NULLHANDLE as the 
input argument. 





@ WinTerminate 





Destroys the anchor block data structure for a thread. 


SYNTAX 
BOOL WintTerminate (HAB hab) 


PARAMETERS 
hab - input 
The anchor block handle to destroy. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinInitialize -10, WinQueryAnchorBlock -11 


NOTES 


Before a thread issues this function, it should destroy any windows and 
message queue created by the thread. 





Registering and 
Creating Windows 





M* Presentation Manager programs create and display at least 
one window to present data to the user and to respond to user in- 
teraction. Creating a window is a two-step process: First the program 
must register a window class and then create a window. Alternatively, 
the program can skip the register step and create a window of a PM- 
registered class, such as a button. 

The WinRegisterClass function accepts as arguments an applica- 
tion-supplied class name string and the address of a window proce- 
dure. So, you can think of the register function as associating the class 
name with the window function. To create a window, then, the pro- 
gram can call WinCreateWindow (or WinCreateStdWindow) and spec- 
ify the registered class name. Since PM has the address of the window 
procedure, it can route messages for the window to the window proce- 
dure. 

When a class is registered, PM internally allocates a data structure 
containing information about the class and provides functions to read 
and write the structure. Similarly, when a window is created, PM allo- 
cates a window data structure that programs can read and modify. The 
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functions to read and write the window data structure are covered in 
Chapter 13: Window Information. 


The Standard Window 


The basic function to create a window is WinCreateWindow, but there 
are other functions that also create windows, such as WinCreate- 
StdWindow, which creates a set of windows collectively called the stan- 
dard window that many PM programs use as their main window. Win- 
CreateStdWindow calls WinCreateWindow internally to create the 
component windows. 

A standard window consists of a frame window, a client window, 
and several optional windows such as a title bar and system menu. The 
frame window is the parent of all of the component windows and con- 
trols most of the behavior of the standard window (such as sizing and 
moving). All of the components of the standard window are PM-regis- 
tered window classes with the exception of the client window (PM pro- 
grams typically register the client window class and specify its class 
name in the WinCreateStdWindow function). The PM program then 
supplies the client window procedure which governs the behavior and 
appearance of the client window. 


Register and Create Window Functions 





WinCalcFrameRect calculates the size of the client window given the 
frame or vice versa (pg 15). 

WinCreateFrameControls creates the component windows of a stan- 
dard window (pg 15). 

WinCreateStdWindow creates the entire collection of windows called a 
standard window (pg 17). 

WinCreateWindow creates a single window (pg 22). 
WinDestroyWindow destroys a window (pg 25). 

WinQueryClassInfo retrieves registered window class information 
(pg 26). 

WinQueryClassName retrieves a class name (pg 27). 
WinRegisterClass registers a window class (pg 28). 
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@ WinCalcFrameRect 





Calculates the size of the client window given the frame or vice versa. 


SYNTAX 

BOOL WinCalcFrameRect (HWND hwndFrame, PRECTL prci, BOOL 
JFrame) 

PARAMETERS 


hwndFrame - input 

Frame window handle. 

prel- input/output 

On input, set to the coordinates of a client window or a frame win- 
dow; on output, returns the coordinates of a client window or a frame 
window. 

fFrame - input 

TRUE - Program supplied a frame rectangle in pre. 

FALSE - Program supplied a client rectangle in prel 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINFRAMEMGR 


SEE ALSO 
WinCreateStdWindow -17, WinQueryWindow -289 


NOTES 


This function sends a WM_CALCFRAMERECT message to the frame 
window. If a program has subclassed the frame window to change the 
size of the client window, the subclass procedure must intercept this 
message and provide the adjusted client rectangle size. 





@ WinCreateFrameControls 





Creates the component windows of a standard window. 
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SYNTAX 


BOOL WinCreateFrameControls (HWND hwndParent, PFRAMEC- 
DATA pdata, PSZ pszTitle) 


PARAMETERS 


hwndParent - input 

Parent window handle. 

pdata - input 

You must allocate and initialize a FRAMECDATA structure and pass 


typedef struct _FRAMECDATA /* fcdata */ 
{ 

USHORT cb; 

ULONG flCreateFlags; 

USHORT hmodResources; 

USHORT idResources; 
} FRAMECDATA; 


cb The size of the structure in bytes. 

flCreateFlags A combination of FCF_* flags that indicate which com- 
ponents of the standard window to create. See WinCreateStd- 
Window (pg 17) for a listing of these flags. 

hmodResources The module handle of the DLL containing the stan- 
dard window’s icon, menu, and accelerator. If these resources are in 
the EXE module, set this field to NULLHANDLE. Ignored unless 
you specify FOF_MENU, FCF_ICON, or FCF_ACCELTABLE. 

idResources The resource identifier assigned to the window's icon, 
menu, and accelerator table. Ignored unless you specify FCF_ 
MENU, FCF_ICON, or FCF_ACCELTABLE. 


pszTitle - input 
The text to be displayed in the title bar window. Ignored unless you 
specify FOF_TITLEBAR. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 
0x1019 - PM_ERR_INVALID_FLAG 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINFRAMEMGR 


Registering and Creating Windows 17 


SEE ALSO 
WinCreateStdWindow -17, WinCreateWindow -22 


NOTES 


A program can use this function instead of WinCreateStdWindow to 
create the standard window in three steps: First create the frame win- 
dow with WinCreateWindow (use classname WC_FRAME), next this 
function to create the component windows (except the client), and 
then call WinCreateWindow to create the client window (specify the 
frame window as parent). 

Alternatively, a program can create the standard window in two 
steps by issuing WinCreateWindow to create the frame window (pass 
the address of a FRAMECDATA structure as the pCtlData parameter) 
and then call WinCreateWindow to create the client. 

Therefore, the main use of this function is to create a standard 
window-like window that uses an application-supplied “frame” window 
class. You can use this function to attach the standard window compo- 
nents to any window class. Note that the application-supplied “frame” 
window must size and position the standard window components. 





WinCreateStdWindow 


Creates the entire collection of windows called a standard window. 


SYNTAX 


HWND WinCreateStdWindow (HWND hwndParent, DLONG 
flframeStyle, PULONG pflCreateFlags, 
PSZ pszClientClass, PSZ pszTitle, 
ULONG flClientStyle, HMODULE 
hmodResource, ULONG ulFramelD, 
PHWND phwndChent) 


PARAMETERS 


hwndParent - input 

The parent of the standard window. Can be HWND_DESKTOP to cre- 
ate a top-level window. 

fiFrameStyle - input 

The window style of the frame window. See WinCreateWindow (pg 22) 
for the WS_* flags. Pass zero for no special frame window styles. 
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pflCreateFlags - input 
Any combination of the frame creation flags that specify standard win- 
dow options: 


Component Windows: The following flags determine which compo- 
nent windows are included in the standard window: 


FCF HIDEBUTTON The standard window contains a hide button. 

FCF HIDEMAX The standard window contains both hide and maxi- 
mize buttons. 

FCF HORZSCROLL The standard window contains a horizontal scroll 


bar. 

FCF MAXBUTTON The standard window contains a maximize 
button. 

FCF MINBUTTON The standard window contains a minimize 
button. 


FCF MINMAX The standard window contains both minimize and 
maximize buttons. 

FCF_SYSMENU The standard window contains a system menu. 

FCF TITLEBAR The standard window contains a title bar. 

FCF _VERTSCROLL The standard window contains a vertical scroll 
bar. 


Border: The following flags determine the border appearance drawn 
by the frame window. 


FCF BORDER The frame draws a thin border. 

FCF_DLGBORDER The frame draws a dialog-style border. 

FCF SIZEBORDER The frame draws a thick border that the user can 
use to size the standard window. 


Standard Window Resources: The following flags determine which re- 
sources the frame window loads and processes. For each flag, there 
must be a corresponding resource whose location is specified by the 
hmodResource parameter. Furthermore, each resource must have the re- 
source identifier specifed by the wl/ramelD parameter. 


FCF_ACCELTABLE The frame loads and processes an accelerator 
table. 

FCF_ICON The frame loads and displays an icon when the standard 
window is minimized. 

FCF_MENU The frame loads and displays a menu. Note that this flag 
also adds a component window to the standard window (window 
ID=FID_MENU). 
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Miscellaneous Flags: 


FCF_AUTOICON If the standard window has an icon, you can specify 
this flag to improve painting performance. With this flag, the win- 
dow will not receive a WM_PAINT message when in the minimized 
state. Instead, PM will draw the icon. 

FCF_MOUSEALIGN Normally used with dialog boxes, this flag 
causes PM to interpet the window’s initial coordinates as being rela- 
tive to the mouse cursor position when the window was created. PM 
attempts to ensure that the entire window remains on the screen. 

FCF_NOBYTEALIGN Without this flag, PM adjusts the coordinates 
of the window on a move operation so that the window's new posi- 
tion lies on a byte boundary in video memory for best performance. 
You specify this flag so you can exactly control a standard window's 
position. 

FCF_ NOMOVEWITHOWNER Without this flag, whenever the stan- 
dard window’s owner is moved, PM also moves the standard window 
by an equivalent amount. 

FCF_SCREENALIGN Normally used with dialog boxes, this flag 
causes PM to interpret the window’s initial coordinates as being rel- 
ative to the top left corner of the screen, rather than relative to the 
window’s parent. 

FCF_SHELLPOSITION Causes PM to assign the standard window an 
initial size and position. Without this flag, the initial size and posi- 
tion are zero. This flag causes PM to issue WinQueryTaskSizePos 
(pg 416) to determine the initial size and position and WinSet- 
WindowPos (pg 311) on the frame window to actually position the 
standard window. 

FCF_SYSMODAL Normally used by modal dialog boxes, this flag 
causes all other windows to be disabled from user input. 

FCF_TASKLIST Causes PM to add the new window’s title to the sys- 
tem window list. PM calls WinAddSwitchEntry (pg 402) to actually 
add the title. 


pszClientClass - input 

The registered class name for the client window component of the 
standard window. You must either first register a private class with 
WinkRegisterClass (pg 28) and pass its name here or use a PM-regis- 
tered class, for example WC_CONTAINER. 

pszTitle - input 

The text to be displayed in the standard window’s title bar. In addition, 
if you specify FCF_TASKLIST as a frame creation flag, PM adds this 
string to the system window list. 
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fiChentStyle - input 

The window style of the client window. See WinCreateWindow (pg 22) 
for the WS_* flags. Pass zero for no special client window styles. 
hmodResource - input 

The module handle of the dynamic link library that contains the stan- 
dard window’s icon, menu, and accelerator table resources. If you bind 
these resources to the program’s EXE file, pass NULLHANDLE for 
this argument. ‘This function ignores this argument unless you specify 
FCF_ICON, FCF_MENU, or FCF_ACCELTABLE. 

ulFramelD - input 

This argument serves two purposes. First, it assigns a window ID to the 
frame window component of the standard window. Second, it uses this 
ID to locate the icon, menu, and accelerator resources contained in 
the module specified by the hmodResource argument. In other words, to 
assign your standard window any of those resources, the resources 
themselves must all have this same ID. 

phwndChent - output 

You must pass the address of an HWND variable where this function 
will return the client window’s handle. 


RETURNS 


NULLHANDLE - An error occurred. 
Other - The frame window’s handle. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_ Ox 1019 - PMERR_ INVALID_ 
HWND FLAG 

Ox100A - PMERR RESOURCE _ 
NOT_FOUND 

OTHER INFO 


Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinCreate Window -22, WinRegisterClass -28 


NOTES 


This function creates the set of windows known as the standard win- 
dow, and returns handles to the required frame and client window 
components. All of the rest of the component windows are optional. 

The component windows created by WinCreateStdWindow are as- 
signed window identifiers as shown in the following list: 
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Component Window ID Class Name 
System Menu FID_SYSMENU WC_MENU 
Title Bar FID_TITLEBAR WC_TITLEBAR 
Min-Max Menu FID_MINMAX WC_MENU 
Action Bar Menu FID MENU WC_MENU 
Vertical Scroll Bar FID_VERTSCROLL WC_SCROLLBAR 
Horizontal Scroll Bar FID_-HORZSCROLL WC_SCROLLBAR 
Client FID_CLIENT application defined 
Frame application defined WC_FRAME 


If you wish the user to see the standard window, either specify 
WS_VISIBLE as a frame window style or issue WinShowWindow (pg 
319) on the frame window handle after creation. 

There is a composite frame creation flag defined in pmwin.h: 
FCF_STANDARD that includes the following creation flags: 


#define FCF_STANDARD FCF_TITLEBAR | FCF_SYSMENU | FCF_MENU | \ 
FCF_SIZEBORDER | FCF_MINMAX | FCF_ICON | \ 
FCF_ACCELTABLE | FCF_SHELLPOSITION | FCF_TASKLIST 


EXAMPLE 

HWND hwndFrame; // Frame window handle 
HWND hwndClient; // Client window handle 
ULONG £1Create; // Frame creation flags 
BOOL fSuccess; // return from API 


fSuccess = WinRegisterClass (hab, “test”, MyWindowProc, 0, 0O ); 


flCreate = FCF_SYSMENU | FCF_SIZEBORDER | FCF_TITLEBAR | 
FCF_MINMAX | FCF_SHELLPOSITION | FCF_TASKLIST | 
FCP _TCON? 


hwndFrame = WinCreateStdWindow (HWND_DESKTOP, WS_VISIBLE 
, &fl1Create, “test”, “Test Program”, 0 


, NULLHANDLE, IDF_MAIN, &hwndClient ); 
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@® WinCreateWindow 





Creates a single window. 


SYNTAX 


HWND WinCreateWindow (HWND hwndParent, PSZ pszClassName, 
PSZ pszText, ULONG /flStyle, LONG x, 
LONG y, LONG cx, LONG cy, HWND 
hwndOwner, HWND hwndlnsertBehind, 
ULONG wllD, PVOID pCilData, PVOID 
pPresParams) 


PARAMETERS 


hwndParent - input 

The new window’s parent window handle. Pass HWND_DESKTOP to 

create a top-level window. 

pszClassName - input 

The registered class name of the window. You must either first register 

a private class with WinRegisterClass (pg 28) and pass its name here or 

use a PM-registered class, for example WC_CONTAINER. 

pszText - input 

The new window’s text. 

fiStyle - input 

The new window’s style, which is a combination of the following flags: 

WS_ANIMATE PM animates the window’s open, close, hide and min- 
imize actions. Note that PM ignores this style if the user has set the 
System Preference for animation to off. 

WS_CLIPCHILDREN PM includes any children of the window when 
it calculates the window’s clipping region. In other words, windows 
with this style cannot draw over their children. Without this style, 
the parent can draw over any children. However, since PM always 
passes WM_PAINT to the parent first and then the children, the 
child windows can repair the damage. 

WS_CLIPSIBLINGS PM includes any siblings of the window when it 
calculates the window’s clipping region. In other words, windows 
with this style cannot draw over their siblings (a sibling is a window 
with the same parent). Without this style, the parent can draw over 
any sibling. However, since PM always passes WM_PAINT to the bot- 
tom window first and then the top, the top windows can repair the 
damage. 
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WS_DISABLED PM prevents the window from receiving user input. A 
program can modify this style dynamically with WinEnableWindow 
(pg 85). 

WS_GROUP In a dialog box, any window with this style marks the be- 
ginning of a group of dialog control windows. The user can press 
the arrow (up, down) keys to cycle through the group members. 

WS_MAXIMIZED You can specify this style on a frame window at cre- 
ation to create the standard window maximized. See WinCreate- 
StdWindow (pg 17). 

WS_MINIMIZED You can specify this style on a frame window at cre- 
ation to create the standard window minimized. See WinCreate- 
StdWindow (pg 17). 

WS_PARENTCLIP PM calculates the clipping for the window to its 
parent’s boundary. Note that windows with this style can draw over 
their parent, so such windows should take care to draw only within 
their own window rectangle. This style speeds up Presentation 
Manager's clipping calculations. 

WS_SAVEBITS PM saves the image underneath this window in a 
bitmap. In other words, if the user moves or closes this window, win- 
dows underneath will not normally receive WM_PAINT messages. 
This style can cause PM to allocate large amounts of memory for the 
bitmap, so it’s not appropriate for large windows. In addition, if the 
underlying windows draw to their window while covered by a win- 
dow of this style, PM cannot use the saved image and must pass 
WM_PAINT anyway. 

WS_SYNCPAINT Causes PM to send WM_PAINT messages to the win- 
dow rather than posting them. 

WS_TABSTOP In a dialog box, the user can press the Tab key to 
change the focus to a window with this style. 

WS_VISIBLE The window is visible if it’s large enough to see and not 
covered by any other windows. Without this style, PM hides the win- 
dow. A program can change this style with WinShowWindow (pg 
319) or WinSetWindowPos (SWP_SHOW) (pg 311). 


x- input 

The window’s initial x-position with respect to its parent’s lower left in 
pixels. A program can change the position with WinSetWindowPos 
(SWP_MOVE) (pg 311). 

y - input 

The window's initial y-position with respect to its parent’s lower left in 
pixels. A program can change the position with WinSetWindowPos 
(SWP_MOVE) (pg 311). 
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cx - input 

The window’s initial width in pixels. A program can change the width 
with WinSetWindowPos (SWP_SIZE) (pg 311). 

cy - input 

The window’s initial height in pixels. A program can change the 
height with WinSetWindowPos (SWP_SIZE ) (pg 311). 

hwndOwner - input 

The new window’s owner window. Most windows pass notification mes- 
sages to their owner. For example, if the user clicks on a button 
(WC_BUTTON class), the button passes the WM_CONTROL message to 
its owner. In addition, PM prevents an owned window from “going be- 
hind” its owner in the stack of windows on the desktop, and destroys 
the owned window when the owner is destroyed. ‘The owned window 
must be in the same thread as the owner. 

hwndInsertBehind - input 

The window handle to insert the new window behind in a set of sib- 
lings. For any group of sibling windows, PM maintains a list called the 
Z-order that determines the siblings’ visible order; that is, which is on 
top. To place the new window at the top of the stack, specify 
HWND_TOP for this argument, HWND_BOTTOM to place it at the bot- 
tom. Otherwise, specify a window that has the same parent as the new 
window. 

ullD - input 

The new window’s identifier. A program can determine the window’s 
handle given this ID and the window’s parent. See WinWindow- 
FromID (pg 322). 

pCtlData - input 

A pointer to a data structure that’s specific for the class of window be- 
ing created. PM passes this pointer to the window as mp2 in the 
WM_CREATE message. This structure must have a USHORT as the first 
field that contains the structure’s size in bytes. Pass NULL if you re- 
quire no control data. 

pPresParams - input 

Window class-specific data for presentation parameters. Pass NULL if 
you require no presentation parameters. 


RETURNS 


NULLHANDLE - An error occurred. 
Other - The window’s handle. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_ Ox 1019 - PMERR_INVALID_ 
HWND FLAG 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinCreateStdWindow -17, WinRegisterClass -28, 
WinSetWindowPos -311, WinWindowFromID -322, 
WinShowWindow -319 


NOTES 


This function creates a single window and returns its handle. During 
this function, PM sends the new window’s procedure the following 
messages: 


WM_CREATE 
WM_ADJUSTWINDOWPOS 


Note that the window does not receive WM_SIZE until the window 
is first sized by the user or via WinSetWindowPos. 

If you use WinCreateWindow to create a frame window 
(WC_FRAME) you can pass the address of a FRAMECDATA (see Win- 
CreateFrameControls, pg 15) as control data to create the rest of the 
components of the standard window (except the client). After using 
WinCreateWindow to create the client, you should then call WinSet- 
WindowPos on the frame to ensure that the frame properly sizes and 
positions the component windows. 





WinDestroyWindow 


Destroys a window. 


SYNTAX 
BOOL WinDestroyWindow (HWND hwnd) 


PARAMETERS 
hwnd - input 
The handle of the window to destroy. 


RETURNS 


TRUE if successful, FALSE if an error occurred. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinCreate Window -22, WinCreateStdWindow -17 


NOTES 


This function also destroys any child or owned windows. This function 
sends the window’s procedure the WM_DESTROY message before the 
child or owned windows are destroyed. The child and owned windows 
will also receive WM_DESTROY. 

If the window has specified a delayed clipboard rendering (see 
WinSetClipbrdData, pg 383), PM also sends the WM_RENDERALL- 
FORMATS message so the window can render the clipboard data. 

If the window is the active window, PM also sends the WM_ACTIT- 
VATE message to the window to inform it that it is losing the active 
state. 





@® WinQueryClassInfo 


Retrieves registered window class information. 


SYNTAX 

BOOL WinQueryClassInfo (HAB hab, PSZ pszClassname, 
PCLASSINFO pClassInfo) 

PARAMETERS 

hab - input 

The anchor block handle. 


pszClassname - input 

The class name to query. 

pClassInfo - output 

PM returns information about the class in this structure: 


typedef struct _CLASSINFO /* clsi */ 
{ 

ULONG f1lClassStyle; 

PFNWP pfnWindowProc; 

ULONG cbWindowData; 

CLASSINFO; 


Ww 


Registering and Creating Windows 27 


flClassStyle The class style flags. See WinRegisterClass (pg 28). 

pfnWindowProc The address of the window procedure for all win- 
dows of this class. 

cbWindowData The amount of extra storage that PM allocates in the 
window data structure for windows of this class. 


RETURNS 
TRUE if successful, FALSE if an error occurred. 
Possible returns from WinGetLastError: 


0x1015 - PMERR_INVALID_ATOM_NAME 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinRegisterClass -28, WinQueryClassName -27 


NOTES 


A program can use this function to obtain the window procedure ad- 
dress, styles, and extra byte count for subclassing all windows of a win- 
dow class (within the same process). In other words, a program can 
register a new Class using the same styles and extra byte count as an al- 
ready registered class and provide a subclass procedure that passes 
messages to the pfnWindowProc function retrieved by this function. 
Note: If the previously registered class has the CS_PUBLIC style, you 
must remove that flag before registering the new class: 


if (clsi.flClassStyle & CS_PUBLIC ) 
clsi.flClassStyle &= ~CS_PUBLIC; 





WinQueryClassName 


Retrieves a class name. 


SYNTAX 


LONG WinQueryClassName (HWND hwnd, LONG cb, PCH 
pchName) 
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PARAMETERS 

hwnd - input 

A window handle of a window belonging to the class to query. 
cb - input 

The length of the string specified by pchName. 

pchName - output 

The returned class name string. 


RETURNS 


Q - An error occurred. 
Other - The class name string’s length, excluding the null terminator. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID_HWND 
0Ox100b - PMERR_INVALID_STRING_PARM 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinRegisterClass -28, WinQueryClassInfo -26 


NOTES 


This function returns the class name string for a window, given its han- 
dle. The function truncates the name if necessary to fit in the output 
string. 

Unfortunately, you cannot first call this function with a zero input 
size to obtain the string’s length for dynamic allocation of the string 
memory. 





@ WinRegisterClass 


Registers a window class. 


SYNTAX 


BOOL WinRegisterClass (HAB hab, PSZ pszClassname, PFNWP pfnup, 
ULONG flClassStyle, ULONG cbExtra) 
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PARAMETERS 

hab - input 

Anchor block handle. 

pszClassname - input 

A null-terminated string for the new class name. 

pfnwp - input 

The address of the window procedure for windows based on this class. 
fiClassStyle - input 

A combination of flags that define the style for the class: 


CS_CLIPCHILDREN Assigns the WS_CLIPCHILDREN style to win- 
dows based on this class. PM includes any children of the window 
when it calculates the window’s clipping region. In other words, win- 
dows with this style cannot draw over their children. Without this 
style, the parent can draw over any children. However, since PM al- 
ways passes WM_PAJNT to the parent first and then the children, the 
child windows can repair the damage. 

CS_CLIPSIBLINGS Assigns the WS_CLIPSIBLINGS style to windows 
based on this class. PM includes any siblings of the window when it 
calculates the window's clipping region. In other words, windows 
with this style cannot draw over their siblings (a sibling is a window 
with the same parent). Without this style, a window can draw over 
any sibling. However, since PM always passes WM_PAINT to the bot- 
tom window first and then the top, the top windows can repair the 
damage. 

CS FRAME Windows of this class are frame windows. 

CS_HITTEST PM should send the WM_HITTEST message before 
sending any mouse messages. 

CS_MOVENOTIFY PM should send the WM_MOVE message. 

CS_PARENTCLIP Assigns the WS_PARENTCLIP style to windows 
based on this class. PM calculates the clipping for the window to its 
parent’s boundary. Note that windows with this style can draw over 
their parent, so such windows should take care to draw only within 
their own window rectangle. This style speeds up Presentation 
Manager’s clipping calculations. 

CS_PUBLIC Registers a public window class. You can only register us- 
ing this style from within a DLL called by the shell upon boot. To 
cause the shell to call your DLL, add your DLL’s name as the data in 
the OS2.INI profile under the application name SYS_DLLS and key 
name LoadOneTime or LoadPerProcess. 

CS_SAVEBITS Assigns the WS_SAVEBITS style to windows based on 
this class. PM saves the image underneath this window in a bitmap. 
In other words, if the user moves or closes this window, windows un- 
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derneath will not normally receive WM_PAINT messages. This style 
can cause PM to allocate large amounts of memory for the bitmap, 
so it’s not appropriate for large windows. In addition, if the under- 
lying windows draw to their window while covered by a window of 
this style, PM cannot use the saved image and must pass WM_PAINT 
anyway. 

CS_SIZEREDRAW PM will entirely invalidate windows that have this 
class style whenever they are resized. Normally, PM only invalidates 
the new part of a window when it is made larger, and does not inval- 
idate it at all if it is made smaller. 

CS_SYNCPAINT Assigns the WS_SYNCPAINT style to windows based 
on this class. Causes PM to send WM_PAINT messages to the window 
rather than posting them. 

cbExtra - input 

The byte count of extra storage that PM should allocate in the window 

data structure of any windows based on this class. A program can use 

WinSetWindowULong (pg 316) or WinSetWindowUShort (pg 317) 

to write to the extra storage and the equivalent query calls to read 

from it. 


RETURNS 
TRUE if successful, FALSE if an error occurred. 
Possible returns from WinGetLastError: 


0x1003 - PMERR_PARAMETER_OUT_OF_RANGE 
0x1019 - PMERR_INVALID_FLAG 
0x1208 - PMERR_INVALID_PARAMETERS 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinQueryClassName -27, WinQueryClassInfo -26, 
WinCreateWindow -22, WinCreateStdWindow -17, 
WinSetWindowUShort -317, WinQueryWindowUShort -298, 
WinSetWindowULong -316, WinQueryWindowULong -296 


NOTES 


This function registers the address of the specified window procedure 
under the specified class name, using the class styles and window extra 
byte count provided. After issuing this function, a program can call 
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WinCreateWindow or WinCreateStdWindow to create windows based 
on this class. 

If a program attempts to register a class with the same name as a 
preregistered public class, this function returns PMERR_PARAME- 
TER_OUT_OF_RANGE. However, it is valid to register again with the 
same name as a private class; the second call replaces the first and no 
error is reported. 

PM deregisters the window class when the calling process termi- 
nates. 

If a program wishes to register a class for a window procedure 
stored in a dynamic link library, the program must first retrieve the ad- 
dress of the window procedure before issuing this function. 





Messaging 
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ll] Presentation Manager programs must respond to events gener- 

ated by the user and by the system itself. These events are called 
messages and consist of a data structure and a call to a window proce- 
dure. In addition, PM programs can pass messages to other windows or 
even other programs. All PM programs must create a message queue as 
part of their initialization. This queue is sufficient for any number of 
application windows. If a program has multiple threads, each thread 
can create its own message queue, but is not required to do so. 

To ensure that the system remain responsive to user actions, PM 
programs should process messages as quickly as possible: PM currently 
passes messages to window procedures one at a time. In other words, if 
a PM program takes a long time to process a message, PM will not pass 
any more messages to that program or other programs until the pro- 
gram returns from the first message. (Actually, PM waits for the pro- 
gram to call WinGetMsg or WinPeekMsg before dispatching subse- 
quent messages.) If a program must execute a lengthy process, for 
example printing, the program should create a separate thread that 
performs the processing. A future version of PM may utilize desyn- 
chronized input queues to alleviate problems caused by programs that 
do not follow this guideline. 
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Posted vs. Sent Messages 


PM provides two techniques for a window procedure to pass messages 
to another window. If a program calls WinPostMsg (pg 44), PM places 
the message in the destination’s message queue; since the caller doesn’t 
wait for receipt, this is called an asynchronous message. It is analagous to 
mailing a letter or sending an electronic mail note. 

For higher priority messages, a program can issue WinSendMsg 
(pg 54), which effectively bypasses the destination’s message queue 
and acts as a direct call. To the caller, sent messages are synchronous 
since PM blocks the caller until the recipient executes a return state- 
ment. Note that PM will not interrupt the destination; even a sent mes- 
sage blocks the caller until the recipient finishes any current message. 
A further advantage of a sent message versus a posted message is that 
PM passes the recipient’s return value back to the caller, so a program 
can use a sent message to query values from another window. An anal- 
ogy for a sent message is when an employee carries a note to a co- 
worker and waits for a reaction while the co-worker reads the note. 

A program can use either technique to pass messages within the 
same process or between processes; PM performs a context switch as 
needed. 
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WinBroadcastMsg passes a message to several windows (pg 35). 
WinCallMsgFilter calls a message filter hook procedure (pg 36). 
WinCheckInput works with MsgInputHook (pg 37). 

WinDispatchMsg calls a window procedure (pg 38). 

WinGetMsg dequeues a message data structure from a message queue 
(pg 39). 

WinInSendMsg determines if a window is currently processing a sent 
message from another thread (pg 42). 

WinPeekMsg lets a program examine the contents of a message queue 
and optionally dequeue a message data structure (pg 43). 
WinPostMsg places a message data structure in a destination window’s 
queue (pg 44). 

WinPostQueueMsg places a message data structure in a destination 


queue (pg 45). 


34 


OS/2 WARP Presentation Manager API 


WinQueryClassThunkProc retreives the address of a thunk procedure 
for a window class (pg 46). 

WinQueryMsgPos retrieves the mouse pointer position at the time of 
a message (pg 47). 

WinQueryMsgTime retrieves the time of a message (pg 48). 
WinQueryQueuelnfo retrieves information about a message queue 
(pg 49). 

WinQueryQueueStatus retrieves the status of a message queue (pg 50). 
WinQueryWindowModel determines if a window is a 16- or 32-bit win- 
dow (pg 51). 

WinQueryWindowThunkProc retreives the address of a thunk proce- 
dure for a window (pg 52). 

WinRegisterUserDatatype is not documented 

WinRegisterUserMsg is not documented 

WinReleaseHook removes a hook procedure from a message hook 
chain (pg 52). 

WinRequestMutexSem waits on a mutual exclusion semaphore or for 
a sent message (pg 53). 

WinSendMsg calls a destination window’s window procedure (pg 54). 
WinSetClassMsgInterest controls which messages are passed to a mes- 
sage control hook procedure for a window class (pg 55). 
WinSetClassThunkProc assigns a thunk procedure for a window class 
(pg 96). 

WinSetHook inserts a hook procedure into a message hook chain 
(pg 57). 

WinSetMsgInterest controls which messages are passed to a message 
control hook procedure for a window (pg 69). 

WinSetMsgMode sets the mode for a message control hook procedure 
(pg 70). 

WinSetSynchroMode sets the mode of the message control hook pro- 
cedure (pg 70). 

WinSetWindowThunkProc assigns a thunk procedure for a window 
(pg 71). 

WinStartTimer schedules a periodic message (pg 72). 

WinStopTimer stops a periodic message (pg 74). 

WinWaitEventSem waits on an event semaphore or a sent message 
(pg 74). 

WinWaitMsg lets a program wait for a specific message or range of mes- 
sages (pg 75). 


WinWaitMuxWaitSem waits on a list of semaphores or a sent message 


(pg 76). 
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@ WinBroadcastMsg 


Passes a message to several windows. 


SYNTAX 


BOOL WinBroadcastMsg (HWND hwndParent, ULONG ulMsg, 
MPARAM mp1, MPARAM mp2, 
ULONG /l) 


PARAMETERS 


hwndParent - input 

The parent of the windows to which PM passes the message. Unless you 
specify BMSG_DESCENDANTS in the fl parameter, this function passes 
messages only to the immediate children of this window. If you specify 
HWND_DESKTOP, it passes messages to children of the desktop. 
ulMsg - input 

The message ID to pass, for example WM_USER. 

mpI - input 

The first message parameter. 

mp2 - input 

The second message parameter. 

fl- input 

The broadcast flags can be any combination of the following, except as 
noted. 


BMSG_DESCENDANTS Pass the message to all descendants of 
hwndParent, not just direct children. 

BMSG_FRAMEONLY Pass the message only to windows with the 
WS_FRAME style. 

BMSG_POST Post the message. Cannot be combined with BMSG_ 
POSTQUEUE or BMSG_SEND. 

BMSG_POSTQUEUE Post the message to all threads that have a 
message queue. PM will set the hwnd field in the resulting QMSG 
structure to NULLHANDLE. Cannot be combined with BMSG_ 
SEND or BMSG_POST. 

BMSG_SEND Send the message. Cannot be combined with BMSG_ 
POSTQUEUE or BMSG_POST. If you specify this flag, WinBroadcast- 
Msg doesn’t return until all of the windows have processed the mes- 
sage. 
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RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinSendMsg -54, WinPostMsg -44, WinPostQueueMsg -45 





@ WinCallMsgFilter 


Calls a message filter hook procedure. 


SYNTAX 
BOOL WinCallMsgFilter (HAB hab, POQMSG pqmsg, ULONG ulCode) 


PARAMETERS 
hab - input 
The anchor block handle. 
pqmsg - input 
The address of a message data structure to pass to the hook procedure: 
typedef struct _OMSG /* qmsg */ 
{ 
HWND hwnd; 
ULONG msg; 
MPARAM mp1; 
MPARAM mp2; 
ULONG time; 
POINTL ptl; 
ULONG reserved; 
} QMSG; 


hwnd The handle of the window receiving the message. 
msg ‘The message identifier. 

mpl ‘The first message parameter. 

mp2 The second message parameter. 

time The time the message was generated. 
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ptl The mouse pointer coordinates at the time the message was gen- 
erated. 
reserved Reserved. 


ulCode - input 
One of the following: 


MSGF_DDEPOSTMSG The message was generated during a dy- 
namic data exchange (DDE) transaction. 

MSGF_DIALOGBOX The message was generated while a modal di- 
alog box was active. 

MSGF_MESSAGEBOX The message was generated while a message 
box was active. 

MSGF_ TRACK ‘The message was generated during a tracking opera- 
tion generated by WinTrackRect (pg 131). 


RETURNS 


The message hook filter will return TRUE if the message was not 
passed to the next hook function, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINHOOKS 


SEE ALSO 


WinTrackRect -131, WinDlgBox -175, WinProcessDlg -190, 
WinMessageBox -184, WinSetHook -57, WinReleaseHook -52 


NOTES 


At certain times, PM restricts message processing while it is in a modal 
loop. For example, while a modal dialog box is displayed, the owner 
window will not receive user-input messages; PM essentially discards 
the messages. If a program needs to processes message during a modal 
loop, it can register a message filter hook procedure with WinSet- 
Hook. PM will call the message filter hook procedure and pass it mes- 
sages during the modal loop. 

Occasionally, a program may need to directly call the message filter 
hook procedure. The program can use this function for that purpose. 





WinCheckinput 


Works with a MsgInputHook. 
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SYNTAX 
BOOL WinCheckInput(HAB had) 


PARAMETERS 
hab - input 
The anchor block handle of the current thread. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WININPUT 


SEE ALSO 
WinSetHook -57 


NOTES 


A program that installs a MsgInputHook must call this function when- 
ever it inserts messages into the system message queue. 





@ WinDispatchMsg 
Calls a window procedure. 


SYNTAX 
MRESULT WinDispatchMsg (HAB hab, POMSG paqmsg) 


PARAMETERS 
hab - input 
The anchor block handle of the current thread. 
pqmsg - input 
The message data structure that describes the message: 
typedef struct _OMSG /* qmsg */ 
{ 
HWND hwnd; 
ULONG msg; 
MPARAM mp1; 
MPARAM mp2; 
ULONG time; 
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POINTL ptl; 
ULONG reserved; 
} QMSG; 


hwnd The handle of the window receiving the message. 

msg The message identifier. 

mpl _ The first message parameter. 

mp2 ‘The second message parameter. 

time The time the message was generated. 

ptl The mouse pointer coordinates at the time the message was gen- 
erated. 

reserved Reserved. 


RETURNS 


The return value passed by the window procedure. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinSendMsg -54, WinGetMsg -39, WinPeekMsg -43 


NOTES 


A PM program typically calls this function after calling WinGetMsg or 
WinPeekMsg which retrieve a message data structure from a message 
queue. 

This function works the same as WinSendMsg in that it synchro- 
nously calls the window procedure specified by the gmsg.hwnd field. 





WinGetMsg 


Dequeues a message data structure from a message queue. 


SYNTAX 


BOOL WinGetMsg (HAB hab, POQMSG pgmsg, HWND hwndFilter, 
ULONG wilFirst, ULONG wilLast) 
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PARAMETERS 

hab - input 

The current thread’s anchor block handle. 
pqmsg - input 


The message data structure that describes the message: 


typedef struct _OMSG /* qmsg */ 
{ 
HWND hwnd; 
ULONG msg; 
MPARAM mp1; 
MPARAM mp2; 
ULONG time; 
POINTL ptl; 
ULONG reserved; 
} OMSG; 


hwnd ‘The handle of the window receiving the message. 

msg ‘The message identifier. 

mpl _ The first message parameter. 

mp2 ‘The second message parameter. 

time ‘The time the message was generated. 

ptl The mouse pointer coordinates at the time the message was gen- 
erated. 

reserved Reserved. 

hwndFilter - input 

The handle of the window for which PM should filter messages. Pass 

NULLHANDLE for no filtering. 

ulFirst - input 

The first message ID to filter. Pass zero to disable filtering. 

ulLast - input 

The last message ID to filter. Pass zero to disable filtering. 


RETURNS 


FALSE if the message was WM_QUIT, TRUE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


Messaging 4] 


SEE ALSO 
WinPeekMsg -43, WinDispatchMsg -38, Win TranslateAccel -258 


NOTES 


This function retrieves a message data structure from a message 
queue. Most PM applications call this function in a loop until the 
WM_QUIT message is encountered. 

If there are no messages in the message queue, this function 
blocks the calling thread until a message is posted into the queue. 

If there are no other messages in the queue and one of the win- 
dows registered on this thread has a non-null invalid region, this func- 
tion generates a WM_PAINT message for that window. 

This function also calls any input or sent message hook proce- 
dures. In addition, this function calls WinTranslateAccel to translate 
WM_CHAR messages into WM_COMMAND, WM_SYSCOMMAND, or 
WM_HELP messages if the program has an accelerator table. 

If there are multiple messages in the queue, this function retrieves 
them in the following order: 


WM_SEM1 
Posted Messages 
WM_SEM2 
WM_TIMER 
WM_SEM3 
WM_PAINT 


A program can change this order by using WinPeekMsg or by fil- 
tering messages. To filter messages, pass a window handle in hwndFilter 
and a range of messages in ulfirst and ulLast. This function will only 
queue messages for that window that fall within the range. Thus, a pro- 
gram could dynamically change ulFirst and ulLast and turn filtering on 
and then off to change the order in which messages are dequeued. 
There are special values you can specify for ulFirst and ulLast instead of 
message IDs: 


WM_MOUSEFIRST Lowest ID for a mouse message. 
WM_MOUSELAST Highest ID for a mouse message. 
WM_BUTTONCLICKFIRST Lowest ID for a click message. 
WM_BUTTONCLICKLAST Highest ID for a click message. 
WM_DDE_FIRST Lowest ID for a dynamic data exchange message. 
WM_DDE_LAST Highest ID for a dynamic data exchange message. 
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EXAMPLE 


Dequeue and dispatch messages until the WM_QUIT message is en- 
countered, with no message filtering. 


QMSG qmsg; 
while ( WinGetMsg ( hab, &qmsg, NULLHANDLE, 0, 0 ) != FALSE ) 
WinDispatchMsg ( hab, &qmsg ); 





@® WinlnSendMsg 


Determines whether a window is currently processing a sent message 
from another thread. 


SYNTAX 
BOOL WinInSendMsg (HAB had) 


PARAMETERS 
hab - input 
The current thread’s anchor block handle. 


RETURNS 


TRUE if the current thread is processing a sent message from another 
thread, 
FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinSendMsg -54, WinIsThreadActive -92, WinMessageBox -184 


NOTES 


If the active window sends a message to a window on another thread, 
the destination window cannot change the active window until it re- 
turns from the sent message. So, if the destination window detects an 
error during that message and needs to display an error message to the 
user, it should use WinMessageBox, which forces an active window 
switch. Otherwise, if the destination window simply writes text to its 
own window, the user may not see the the error text. 
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@ WinPeekMsg 


Lets a program examine the contents of a message queue and option- 
ally dequeue a message data structure. 


SYNTAX 


BOOL WinPeekMsg (HAB hab, PQMSG pgmsg, HWND hwndFilter 
ULONG ulFirst, ULONG ulLast, ULONG f) 


PARAMETERS 
hab - input 
The current thread’s anchor block handle. 
pqmsg - input 
The message data structure that describes the message: 
typedef struct _QMSG /* qmsg */ 
{ 
HWND hwnd; 
ULONG msg; 
MPARAM mpl; 
MPARAM mp2; 
ULONG time; 
POINTL ptl; 
ULONG reserved; 
} QMSG; 


hwnd The handle of the window receiving the message. 

msg ‘The message identifier. 

mpl The first message parameter. 

mp2 The second message parameter. 

time The time the message was generated. 

ptl The mouse pointer coordinates at the time the message was gen- 
erated. 

reserved Reserved. 


hwndFilter - input 

The handle of the window for which PM should filter messages. Pass 
NULLHANDLE for no filtering. 

ulFirst - input 

The first message ID to filter. Pass zero to disable filtering. 

ulLast - input 

The last message ID to filter. Pass zero to disable filtering. 


44 OS/2 WARP Presentation Manager API 


fl- input 
One of the following flags: 


PM _NOREMOVE Retrieve the message data structure but leave it in 
the queue. 
PM_REMOVE  Dequeue the message data structure from the queue. 


RETURNS 
TRUE if a message data structure was returned, FALSE if not. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinGetMsg -39, WinDispatchMsg -38 


NOTES 


This function lets a thread examine its message queue and optionally 
dequeue a message. The main difference between this function and 
WinGetMsg is that WinPeekMsg doesn’t block the calling thread if the 
message queue is empty. Thus, you can use WinPeekMsg in a back- 
ground thread to poll for messages posted from another thread. For 
more information on message filtering, see WinGetMsg. 





@ WinPostMsg 


Places a message data structure in a destination window's queue. 


SYNTAX 


BOOL WinPostMsg (HWND hwndDest, ULONG ulMsg, MPARAM 
mp1, MPARAM mp2) 


PARAMETERS 


hwndDest - input 

The window to receive the message. 
ulMsg - input 

The message identifier. 
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mpI - input 

The first message parameter. 
mp2 - input 

The second message parameter 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_ 0x1038 - PMERR_QUEUE_ 
HWND FULL 
OTHER INFO 


Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinSendMsg -54, WinPostQueueMsg -45 


NOTES 


This function allocates a QMSG structure and places it in the destina- 
tion window’s queue and then returns immediately; PM passes the 
message asynchronously to the destination. The return from this func- 
tion indicates whether the message was queued. This function differs 
from WinSendMsg, which blocks the caller until the destination 
processes the message. 

The ulMsg, mpl, and mp2 parameters are specific to the message 
being posted. 

If you wish to post a message to a thread that has no window but 
does create a message queue, use WinPostQueueMsg instead of this 
function. 





WinPostQueueMsg 


Places a message data structure in a destination queue. 


SYNTAX 


BOOL WinPostQueueMsg (HMQ hmqDesit, ULONG ulMsg, MPARAM 
mpl, MPARAM mp2) 
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PARAMETERS 

hmqDest - input 

The message queue to receive the message. 
ulMsg - input 

The message identifier. 

mpI - input 

The first message parameter. 

mp2 - input 

The second message parameter 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1002-PMERR INVALID. —0x1038 - PMERR_QUEUE_ 
HMQ FULL 
OTHER INFO 


Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinSendMsg -54, WinPostMsg -44 


NOTES 


This function allocates a QMSG structure and places it in the destina- 
tion queue and then returns immediately; PM passes the message asyn- 
chronously to the destination. The return from this function indicates 
whether the message was queued. This function differs from Win- 
SendMsg which blocks the caller until the destination processes the 
message. 

The ulMsg, mpl, and mp2 parameters are specific to the message 
being posted. 

This function differs from WinPostMsg in that it lets you post a 
message to a thread that has no window, but does have a message 
queue. 





@ WinQueryClassThunkProc 


Retrieves the address of a thunk procedure for a window class. 
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SYNTAX 
PFN WinQueryClassThunkProc (PSZ pszClass) 


PARAMETERS 
pszClass - input 
A null-terminated string that indicates the class name to query. 


RETURNS 
The address of the thunk procedure if successful, NULL otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINTHUNKAPI 


SEE ALSO 


WinSetClassThunkProc -56, WinQueryWindowThunkProc -52, 
WinSetWindowTlhunkProc -52, WinQueryWindowModel -51 


NOTES 


When a 16-bit program passes a message containing pointers to a 32- 
bit program, the pointers must be converted from 16-bit to 32-bit con- 
vention. You can call this function to query the function that converts 
pointers for all windows of a given class. 





WinQueryMsgPos 
Retrieves the mouse pointer position at the time of a message. 


SYNTAX 
BOOL WinQueryMsgPos (HAB hab, PPOINTL ppil) 


PARAMETERS 
hab - input 
The current thread’s anchor block handle. 


pptl - output 
Pass the address of a POJNTL structure that this function fills with the 


mouse pointer position. 


RETURNS 
TRUE if successful, FALSE otherwise. 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinQueryMsg Time -48, WinQueryPointerPos -250 


NOTES 


A program can call this function to retrieve the mouse pointer coordi- 
nates at the time the message was generated. Note that the user may 
have moved the mouse since the message was created. To obtain the 
current pointer coordinates, call WinQueryPointerPos instead. 





@ WinQueryMsgTime 
Retrieves the time of a message. 


SYNTAX 
ULONG WinQueryMsgTime (HAB hab) 


PARAMETERS 
hab - input 
The current thread’s anchor block handle. 


RETURNS 


The time (in milliseconds) the current message was generated. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinQueryMsgPos -47, WinQueryPointerPos -250 


NOTES 


A program can call this function to retrieve the system time the mes- 
sage was generated. The time value is the number of milliseconds since 
the system was booted. You can calculate the time difference between 
messages by subtracting the second message time from the first, but be 
aware that the system time is stored in a ULONG and will wrap back to 
zero after 232-1 milliseconds. 
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@ WinQueryQueuelnfo 


Retrieves information about a message queue. 


SYNTAX 

BOOL WinQueryQueuelnfo (HMQ hmq, PMQINFO pind, 
ULONG cb) 

PARAMETERS 

hmg - input 


The handle of the queue to query. 
pmqi - output 
Pass the address of a MQ/NFO structure that this function fills in: 


typedef struct _MQINFO /* mqi */ 
{ 


ULONG cb; 
Pip pid 
+L) tid 


ULONG cmsgs; 
PVOID pReserved; 
} MOQINFO; 


cb The size of the structure in bytes. 

pid The ID of the process that created the queue. 

tid The ID of the thread that created the queue. 

cmsgs ‘The total number of messages currently in the queue. 
pReserved Reserved. 


cb - input 
The size of the MQ/NFO structure. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1002 - PMERR_ INVALID _HMQ 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 
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SEE ALSO 
WinQueryQueueStatus -50 





@® WinQueryQueueStatus 


Retrieves the status of a message queue. 


SYNTAX 
ULONG WinQueryQueueStatus (HWND hwndDesktop) 


PARAMETERS 


hwndDeshtop - input 
The desktop window handle. 


RETURNS 


The returned ULONG is split into 16-bit components that you can sep- 
arate with the LOUSHORT and HIUSHORT macros. Both components 
contain a combination of the flags shown below. The least significant 
16 bits contain the summary of messages in the queue; the most sig- 
nificant 16 bits contain only the messages that have been added to the 
queue since the last invocation of this function. 


OS KEY A WM_CHAR message is in the queue. 

QOS MOUSE Any message from the mouse is in the queue. 

OS MOUSEBUTTON A mouse button click message is in the 
queue. 

OS MOUSEMOVE A WM_MOUSEMOVE message is in the queue. 

QS _MSGINPUT A message from the mouse or keyboard is in the 
queue. 

QS_PAINT A window served by the queue has an invalid region. A 
subsequent WinGetMsg or WinPeekMsg will generate a WM_PAINT 
message. 

QS_POSTMSG A posted message of any type is in the queue. This in- 
cludes user input messages. 

OS SEMI A WM_SEMI message is in the queue. 

OS SEM2 A WM_SEM2 message is in the queue. 

QS_SEM3 A WM_SEM3 message is in the queue. 

OS SEM4 A WM_SEM# message is in the queue. 

QS_SENDMSG A window served by this queue has an outstanding 
sent message. 

OS TIMER A WM_TIMER message is in the queue. 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinQueryQueuelnfo -49 





WinQueryWindowModel 


Determines whether a window is a 16- or 32-bit window. 


SYNTAX 
LONG WinQueryWindowModel(HWND hwnd) 


PARAMETERS 
hwnd - input 
The window to query. 


RETURNS 
One of the following values: 


PM MODEL 1X 16-bit window. 
PM MODEL 2X 32-bit window. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINTHUNKAPI 


SEE ALSO 


WinSetClass ThunkProc -56, WinQueryClassThunkProc -46, 
WinSetWindowThunkProc -71, 


NOTES: 


When a 16-bit program passes a message containing pointers to a 32- 
bit program, the pointers must be converted from 16-bit to 32-bit con- 
vention. The equivalent operation must be performed from 32 to 16 
bits. You can call this function to query whether a window is 16 or 32 
bits. 


52 OS/2 WARP Presentation Manager API 





@® WinQueryWindowThunkProc 


Retrieves the address of a thunk procedure for a window. 


SYNTAX 
PFN WinQueryWindowThunkProc (HWND hwnd) 


PARAMETERS 
hwnd - input 
The window to query. 


RETURNS 
The address of the thunk procedure, NULL otherwise. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINTHUNKAPI 


SEE ALSO 


WinSetClassThunkProc -56, WinQueryClassThunkProc -46, 
WinSetWindowThunkProc -71, WinQueryWindowModel -51 


NOTES 


When a 16-bit program passes a message containing pointers to a 32- 
bit program, the pointers must be converted from 16-bit to 32-bit con- 
vention. The equivalent operation must be performed from 32 to 16 
bits. You can call this function to query the function that converts 
pointers for a given window. 





@ WinReleaseHook 





Removes a hook procedure from a message hook chain. 


SYNTAX 


BOOL WinReleaseHook (HAB hab, HMQ hmgq, LONG I[Type, PFN 
pfn, HMODULE hmod) 


Messaging 53 


PARAMETERS 

hab - input 

The current thread’s anchor block handle. 

hmg - input 

The queue where the hook procedure is installed. Pass HMQ_CUR- 
RENT to release a hook on the current thread’s queue. Pass NULL- 
HANDLE to release a hook on the system queue. 

[Type - input 

The type of hook procedure to release. See WinSetHook for a list of 
hook types. 

pn - input 

The address of the hook function to release. 

hmod - input 

The module handle of the DLL containing the hook procedure. If the 
hook procedure is in the current EXE module, pass NULLHANDLE. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1002 - PMERR_INVALID_HMQ 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINHOOKS 


SEE ALSO 
WinSetHook -57 


NOTES 


This function removes a hook procedure that was installed by WinSet- 
Hook. 





WinRequestMutexSem 


Waits on a mutual exclusion semaphore or for a sent message. 


SYNTAX 
ULONG WinRequestMutexSem (HMTX hmtx, ULONG wulTimeout) 
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PARAMETERS 

hmtx - input 

A mutual exclusion semaphore handle created by DosCreateMutex- 
Sem. 

ulTimeout - input 

The maximum number of milliseconds to wait before returning a 
time-out error. Pass SEM INDEFINITE_WAIT for no timeout, or 
SEM_IMMEDIATE_RETURN to poll the semaphore. 


RETURNS 


0 - NO ERROR 6 - INVALID HANDLE 
640 - TIMEOUT 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


NOTES 


This call waits on the specified mutex semaphore but also processes 
message sent to the window that issues the function. If you need to is- 
sue this function from a process other than the process that created 
the mutex semaphore, you must first issue DosOpenMutexSem in that 
process. 





@ WinSendMsg 


Calls a destination window’s window procedure. 


SYNTAX 


MRESULT WinSendMsg (HWND hwndDest, ULONG wulMsg, 
MPARAM mp1, MPARAM mp2) 


PARAMETERS 


hwndDest - input 

The window to which to send the message. 
ulMsg - input 

The message identifier. 

mpI - input 

The first message parameter. 

mp2 - input 

The second message parameter 
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RETURNS 


The return value from the destination window procedure. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 


WinPostMsg -44, WinPostQueueMsg -45, WinSendDlgItemMsg -199, 
WinCreateMsgQueue -3 


NOTES 


This function synchronously calls the window procedure designated by 
the hwndDest argument—it blocks the caller until the window proce- 
dure returns. If the destination window procedure is in another thread 
or process, this function will perform any necessary thread or process 
switch to complete the message. Note that this function effectively by- 
passes the message queue and, thus, sent messages have a higher pri- 
ority than posted messages. 

Any thread that issues this function must have a message queue 
created by WinCreateMsgQueue on that thread. 





WinSetClassMsginterest 


Controls which messages are passed to a message control hook proce- 
dure for a window class. 


SYNTAX 


BOOL WinSetClassMsgInterest (HAB hab, PSZ pszClassname, 
ULONG wulMsg, LONG [Control) 


PARAMETERS 

hab - input 

The calling thread’s anchor block handle. 
pszClassname - input 

The name of the window class to control messages. 
ulMsg - input 
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The message(s) to set the interest level for. You can pass a single mes- 
sage identifier or SMIJM_ALL for all messages. 

[Control - input 

One of the following flags: 


SMI_AUTODISPATCH Hook should be passed the message(s) but 
also dispatched to the window procedure. 

SMI_INTEREST Hook should be passed the message(s). 

SMI_NOINTEREST Hook should not be passed the message(s). 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_ INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinSetMsgInterest -69, WinSetHook -57 


NOTES 


A program can install a MsgControlHook to intercept messages. This 
function calls that hook. 





@ WinSetClassThunkProc 





Assigns a thunk procedure for a window class. 


SYNTAX 
BOOL WinSetClassThunkProc (PSZ pszClassname, PFN pjfn) 


PARAMETERS 

pszClassname - input 

A null-terminated string that specifies the name of a window class. 

pfn - input 

Pass the address of the function that you wish to assign as the thunk 
procedure for all windows you subsequently create of pszClassname. 
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RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINTHUNKAPI 


SEE ALSO 


WinQueryClassThunkProc -46, WinQueryWindowThunkProc -52, 
WinSetWindowTLhunkProc -56, WinQueryWindowModel -51 


NOTES 


When a 16-bit program passes a message containing pointers to a 32- 
bit program, the pointers must be converted from 16-bit to 32-bit con- 
vention. You can call this function to set the function that converts 
pointers for all windows of a given class. The prototype for the thunk 
procedure is: 


MRESULT ThunkProc (HWND hwnd, USHORT usMsgID, MPARAM 
mpl, MPARAM mp2, PFNWP pfnwp) 

hwnd 

The handle of the 32-bit window procedure. 

usMsgID 

The message identifier (should be greater than WM_USER). 

mp1 

The first message parameter. 

mp2 

The second message parameter. 

pfnwp 

The address of the 32-bit window procedure. 

The thunk function should convert the message parameters and 
then call the 32-bit window procedure. The thunk function must also 
convert any return values as required. If the the thunk procedure is 
called with a message identifier it does not recognize, it should call the 
32-bit window procedure with usMsg set to zero and mp1 and mp2 un- 
changed. 





WinSetHook 


Inserts a hook procedure into a message hook chain. 
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SYNTAX 


BOOL WinSetHook (HAB hab, HMQ hmg, LONG I[Type, PEN pfn, 
HMODULE hmod) 


PARAMETERS 

hab - input 

The current thread’s anchor block handle. 

hmq - input 

The handle of the queue to hook. Pass HMQ_CURRENT to hook the 
current thread’s queue or pass NULLHANDLE to hook the system 
queue. 

[Type - input 

One of the following values: 


HK CHECKMSGFILTER PM calls this hook whenever a program 
uses message filtering with WinGetMsg (pg 39) or WinPeekMsg 
(pg 43). 

HK CODEPAGECHANGED PM calls this hook whenever the code 
page has been changed. 

HK DESTROYWINDOW PM calls this hook when a window is de- 
stroyed. 

HK_FINDWORD PM calls this hook during WinDrawText (pg 122) 
to determine line breaks. 

HK FLUSHBUF PM calls this hook during shutdown. Only available 
in OS/2 2.1 and later. 

HK HELP PM calls this hook when the user requests help. 

HK INPUT PM calls this hook for messages posted to a message 
queue. 

HK_JOURNALPLAYBACK PM calls this hook to allow the hook to 
insert user-input messages into the system queue. 

HK _JOURNALRECORD PM calls this hook during user-input mes- 
sages. 

HK_LOADER PM calls this hook when a dynamic link library is 
loaded or freed, or when a program querys a procedure address. 
HK_LOCKUP PM calls this hook when the system is locked up. Only 

available in OS/2 2.1 and later. 

HK _MSGCONTROL PM calls this hook to let the hook intercept 
messages. 

HK_MSGFILTER PM calls this hook during a modal loop. 

HK_MSGINPUT PM calls this hook to let the hook insert user-input 
messages into the system queue. Similar to the HK_/JOURNALPLAY- 
BACK, but only available in OS/2 2.1 and later. 

HK_SENDMSG PM calls this hook during WinSendMsg (pg 54). 
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pfn - input 

Pass the address of the hook procedure. If you pass NULLHANDLE 
for the hmq argument, the hook procedure must be in a dynamic link 
library. 

hmod - input 

The module handle of the dynamic link library that contains the hook 
procedure. If the hook procedure is in the current executable, pass 
NULLHANDLE. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001-PMERR INVALID. — 0x 1002 - PM_ERR_INVALID_ 
HWND HMQ 
OTHER INFO 


Include file: pmwin.h Define: INCL_WINHOOKS 


SEE ALSO 
WinReleaseHook -52, WinCreateMsgQueue -3 


NOTES 


A program can install a hook to intercept messages or events in the sys- 
tem. When finished, you should unhook the procedure with Win- 
ReleaseHook. You can install serveral hook procedures of the same 
type on the same queue; if you do so, PM organizes the procedures 
into a last-in first-out chain. 

There are two levels of message queues: the global system event 
queue and a thread message queue created with WinCreateMsgQueue. If 
you hook the system event queue, the hook procedure must reside in 
a dynamic link library, and you must pass the DLL’s module handle in 
the hmod argument. You can obtain the module handle with DosLoad- 
Module or DosQueryModuleHandle. 

The [Type argument identifies which event the program wishes to 
intercept. Each event type requires a hook procedure. The hook pro- 
cedure function prototypes are described in the next section. Several 
of the hook procedures are passed the address of a QMSG structure: 


typedef struct _OMSG /* gqmsg */ 
{ 

HWND hwnd; 

ULONG msg; 
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MPARAM mp1; 

MPARAM mp2; 

ULONG time; 

POINTL ptl; 

ULONG reserved; 
} QMSG; 


hwnd The handle of the window receiving the message. 

msg ‘The message identifier. 

mpl ‘The first message parameter. 

mp2 ‘The second message parameter. 

time ‘The time the message was generated. 

ptl ‘The mouse pointer coordinates when the message was generated. 
reserved Reserved. 


Hook Procedure Function Prototypes 


HK_CHECKMSGFILTER: PM calls this hook whenever a program 
uses message filtering with WinGetMsg or WinPeekMsg 


BOOL EXPENTRY CheckMsgFilterHook (HAB hab, POMSG pQmszg, 
ULONG usfirst, ULONG 
usLast, ULONG fOptions) ; 

hab - input 

Installer’s anchor block handle. 

pQmsg- input 

The address of a QMSG structure describing the current message. 

usFirst - input 

First message identity. 

usLast - input 

Last message identity. 

fOptions - input 

One of the following: PM_REMOVE or PM_NOREMOVE. 


VALUE TO RETURN 


TRUE to specify that the hook procedure accepts the message and that 
PM should ignore any filtering specified by WinGetMsg or WinPost- 
Msg. PM does not call any subsequent hook procedures in the chain. 
FALSE to pass the message to the next hook procedure in the chain. If 
no hook procedure returns TRUE, then PM applies the filtering spec- 
ified by WinGetMsg or WinPostMsg. 
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HK CODEPAGECHANGED: PM calls this hook whenever the code 
page has been changed. 


VOID EXPENTRY CodePageChangedHook(HMQ hmg, ULONG 
usOldCodepage, ULONG 
usNewCodepage) 


hmq - input 

The handle of the message queue where the code page is changing. 
usOldCodepage - input 

The previous code page. 

us New Codepage - input 

The new code page. 


VALUE TO RETURN 


None. PM always calls any subsequent hook procedure in the chain. 
HK DESTROYWINDOW: PM calls this hook when a window is de- 


stroyed. 

BOOL EXPENTRY DestroyWindowHook (HAB hab, HWND hwnd, 
ULONG Reserved); 

hab - input 

Anchor block handle. 

hwnd - input 


The handle of the window being destroyed. 
Reserved - input 
Not currently used. 


VALUE TO RETURN 


TRUE if successful, FALSE otherwise. 

HK_FINDWORD: PM calls this hook during WinDrawText (pg -122) 
to determine line breaks. Note that this hook is only called if 
DT_WORDBREA Kis specified. 


BOOL EXPENTRY FindWordHook(ULONG usCodepage, PSZ pszText, 
ULONG cb, ULONG ich, 
PULONG pichStart, PULONG 
pichEnd, PULONG pichNext) 


us Codepage - input 

The text string’s code page. 
pszText - input 

The text string being drawn. 
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cb - input 

The text string’s length. 

ich - input 

The character index of the character that intersects the right edge of 
the formatting rectangle. 

pichStart - ouput 

Set this to the character index of the first character in the word that 
will be broken to the next line. 

pichEnd - output 

Set this to the character index of the last character in the word that will 
be broken to the next line. 

pichNext - ouput 

Set this to the character index of the first character in the following 
word in the string. 


VALUE TO RETURN 


TRUE if successful, FALSE otherwise. If you return FALSE, WinDraw- 
Text draws the string in its normal fashion. 

HK FLUSHBUF: PM calls this hook during shutdown. Only available 
in OS/2 2.1 and later. Note: You should not call any Win or Gpi func- 
tions from this hook procedure. 


BOOL EXPENTRY FlushBufHook (HAB hab) 
hab - input 
Anchor block handle. 


VALUE TO RETURN 


TRUE if successful, FALSE otherwise. 

HK_HELP: PM calls this hook when the user requests help. A user can 
request help by pressing the F1 key while a frame window is active, 
while a menu is active, or when a dialog is active. PM calls the help 
hook with a different mode argument for each case. The topic and 
subtopic arguments then further describe the user’s help request. 
Note: As an alternative to installing a help hook, a PM program can use 
the Information Presentation Facility, which itself uses the help hook 
to display help screens. 


BOOL EXPENTRY HelpHook (HAB hab, ULONG usMode, ULONG 
id Topic, ULONG idSubTopic, PRECTL 
prclPosition) 

hab - input 

Anchor block handle 
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usMode - input 
Describes the situation from which the user requested help. 


HLPM_FRAME A frame window was active (possibly a message box 
or dialog). 

HLPM MENU A menu window had the focus. 

HLPM WINDOW A standard window was active. 


tdTopic - input 

Further information about the help request. If usMode is HLPM_ 
MENU, idTopic contains the window ID of a submenu. If usMode is 
AHLPM_FRAME or HLPM_STANDARD, idTopic contains the window ID 
of the active frame window. 

idSub Topic - input 

Further information about the help request. If usModeis HLPM_MENU, 
idSubTopic contains the menu-item ID that is currently selected. If 
usMode is HLPM_FRAME or HLPM_STANDARD, idSubTopic contains 
the window ID of the current focus window in the standard window or 
dialog; -1 if none. 

prelPosttion - input 

The address of a RECTL structure that contains the coordinates of the 
current focus window so the hook can position any help window. The 
coordinates are in pixels, relative to the lower left of the screen. 


VALUE TO RETURN 


TRUE if you want PM to call the next chained hook procedure, FALSE 
otherwise. 

HK_ INPUT: PM calls the hook during WinGetMsg or WinPeekMsg for 
all messages posted to the queue. 


BOOL EXPENTRY InputHook (HAB hab, POMSGpQmsg, ULONG fs) 
hab - input 

Anchor block handle. 

pQmsg - input 

The address of a QMSG structure (see above) that describes the cur- 
rent message. 

fs- input 

One of the following: 

PM_REMOVE The message will be removed from the queue. 
PM_NOREMOVE The message will stay in the queue. 
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VALUE TO RETURN 


TRUE if you want PM to call the next chained hook procedure or pass 
the message to the program, FALSE otherwise. 
HK_JOURNALPLAYBACKE: PM calls this hook to let a program insert 
messages, typically user-input messages, into the queue. 


ULONG EXPENTRY JournalPlaybackHook (HAB hab, BOOL /fSkip, 
PQMSG /pQmsg) 

hab - input 

Anchor block handle. 

[Skip - input 

If TRUE, the hook procedure should skip to the next buffered mes- 

sage and not fill in the pQmsg parameter. If FALSE, the hook proce- 

dure should fill in pQmsgwith the current buffered message, and keep 


returning that same message until PM calls the hook with this argu- 
ment TRUE. 


pQmsg - input/output 
The address of a QMSG structure (described above) that the hook pro- 


cedure should fill in. PM sets the time field of this structure with the 
current time. 


VALUE TO RETURN 


The number of milliseconds PM should wait before inserting this mes- 
sage into the queue. 

HK _JOURNALRECORD: PM calls this hook whenever user input oc- 
curs. 


VOID EXPENTRY JournalRecordHook (HAB hab, POMSG pQmsg) 
hab - input 

Anchor block handle. 

pOmsg - input 

The address of a QMSG structure (documented above) that describes 
the user input message. 

HK_LOADER: PM calls this hook whenever a program calls the Win 
dynamic linking functions. The hook must perform the library load- 
ing and unloading. 


BOOL EXPENTRY LoaderHook (HAB hab, LONG idContext, PSZ 
pszLibname, PHLIB philib, PSZ 
pszProcname, PFNWP. wndProc) 
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hab - input 

Anchor block handle. 

id Context - input 

One of the following values: 


LHK_DELETELIB WinDeleteLibrary was called. 

LHK DELETEPROC WinDeleteProcedure was called. 

LHK_LOADLIB WinLoadLibrary was called. The hook must load 
the library indicated by the pszLibname argument and return its han- 
dle in the phliib argument. 

LHK LOADPROC WinLoadProcedure was called. The hook must 
must return the address of the function specified by pszProcname in 
the wndProc argument. 


pszLibname - input 

A string containing the name of the libary being loaded. 

phlb - input/output 

The address of the handle of the library. ‘This argument is an input pa- 
rameter except for LHK_LOADLIB, where the hook function must 
load the library and return its handle using the pointer. 

pszProcname - input 

A string containing the name of the function being loaded. 

wndProc - input/output 

The address of the function being loaded or unloaded.This argument 
is an input parameter except for LHK_LOADPROC, where the hook 
function must determine the function’s address and return it using the 
pointer. 


VALUE TO RETURN 


TRUE if you want PM to call the next chained hook procedure or pass 
the message to the program, FALSE otherwise. 

HK LOCKUP: PM calls this hook when the system is locked. This 
hook is only available in OS/2 2.1 and later and must be installed on 
the system queue. 


BOOL EXPENTRY LockupHook (HAB hab, HWND hwndLockupFrame) 
hab - input 

Anchor block handle. 

hwndLockupFrame - input 

The handle of the frame window that displayed the lockup message. 
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VALUE TO RETURN 


TRUE if you want PM to call the next chained hook procedure or pass 
the message to the program, FALSE otherwise. 

HK_MSGCONTROL: PM calls this hook during WinSetClassMsgIn- 
terest, WinSetMsgInterest, WinSetMsgMode, or WinSetSynchroMode. 


BOOL EXPENTRY MsgControlHook (HAB hab, LONG idContext, 
HWND hwnd, PSZ 
pszClassname, ULONG 
usMsgclass, LONG idControl, 
PBOOL /Success) 


hab - input 

Anchor block handle. 
id Context - input 

One of the following: 


MCHK_CLASSMSGINTEREST WinSetClassMsgInterest was called. 
MCHK_MSGINTEREST WinSetMsgInterest was called. 

MCHK MSGMODE WinSetMsgMode was called. 
MCHK_SYNCHRONISATION  WinSetSynchroMode was called. 


hwnd - input 

The window handle passed in WinSetMsgInterest. 

pszClassname - input 

The class name string passed in WinSetClassMsgInterest. 
usMsgClass - input 

The message ID of interest or SMIM_ALL. 

idControl - input 

For MCHK_CLASSMGSINTEREST or MCHK_MSGINTEREST: 


SMI_AUTODISPATCH 
SMI_INTEREST 
SMI_NOINTEREST 
SMI_RESET 


For MCHK_MSGMODE: 


SMD_DELAYED 
SMD_IMMEDIATE 


For MCHK_SYNCHRONISATION: 


SSM_SYNCHRONOUS 
SSM_ASYNCHRONOUS 
SSM_MIXED 
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Success - output 
The address of a BOOL that the hook should set: TRUE if successful, 
FALSE otherwise. 


VALUE TO RETURN 


TRUE if you want PM to call the next chained hook procedure or pass 
the message to the program, FALSE therwise. 
HK_MSGFILTER: PM calls this hook during modal loops. 


BOOL EXPENTRY MsgFilterHook (HAB hab, PQMSG pQmszg, 
ULONG msg/f) 

hab - input 

Anchor block handle. 

pQmsg - input 

The address of a QMSG structure (documented above) that describes 

the current message. 

msgf - input 

One of the following values that describe the modal loop in progress: 


MSGF_DDEPOSTMSG A DDE message is in progress. 
MSGF_DIALOGBOX A modal dialog box is in progress. 
MSGF_MESSAGEBOX A message box is in progress. 
MSGF_TRACK A size or move tracking rectangle is in progress. 


VALUE TO RETURN 


TRUE if you want PM to call the next chained hook procedure or pass 
the message to the program, FALSE otherwise. 

HK_MSGINPUT: PM calls this hook to let a program insert messages 
into a queue. This hook is only available in OS/2 2.1 and later. 


BOOL EXPENTRY MsgInputHook (HAB hab, PQMSG pQmsg, BOOL 
Skip, PBOOL pfNoRecord) 

hab - input 

Anchor block handle 

pQmsg - output 

The address of a QMSG structure (described above) that the hook pro- 

cedure should fill in. 

[Skip - input 

If TRUE, the hook procedure should skip to the next buffered mes- 

sage and not fill in the pQmsg parameter. If FALSE, the hook proce- 

dure should fill in pQmsg with the current buffered message, and keep 
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returning that same message until PM calls the hook with this argu- 
ment TRUE. 


pfNoRecord - output 


The address of a BOOL that this hook should set to indicate whether 
PM should pass the message to any journal record hook. Normally, you 
should set this to TRUE to indicate that the message should not be 
recorded. 


VALUE TO RETURN 


Return TRUE if you want the message to be inserted into the queue, 
FALSE if you have no more messages to playback. Note: You must also 
call WinCheckInput (pg -37). 

HK_SENDMSG: PM calls this hook during WinSendMsg. 


VOID EXPENTRY SendMsgHook (HAB hab, PSPMHSTRUCT psmh, 
BOOL /flnierTask) ; 

hab - input 

Anchor block handle. 

psmh - input 

A pointer to a SMHSTRUCT that describes the sent message: 


typedef struct _SMHSTRUCT /* smhs */ 
{ 
MPARAM mp2; 
MPARAM mp1; 
ULONG msg; 
HWND hwnd; 
ULONG model; 
{ $MHSTRUCT; 


mp2 The second message parameter. 
mpl The first message parameter. 
msg ‘The message identifier. 

hwnd The destination window handle. 
model One of the following values: 
PM_MODEL_1X 16-bit message. 

PM MODEL _2X 32-bit message. 


finterTask - input 
PM sets this to TRUE if the message was sent from another thread, 
FALSE otherwise. 
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@ WinSetMsginterest 


Controls which messages are passed to a message control hook proce- 
dure for a window. 


SYNTAX 


BOOL WinSetMsgInterest (HWND hwnd, ULONG ulMseClass, 
LONG [Control) 


PARAMETERS 

hwnd - input 

The handle of the window to control messages. 

ulMsgClass - input 

The message(s) to set the interest level for. You can pass a single mes- 
sage identifier or SMIM_ALL for all messages. 


[Control - input 

One of the following flags: 

SMI_AUTODISPATCH Hook should be passed the message(s) but 
also should be dispatched to the window procedure. 


SMI_INTEREST Hook should be passed the message(s). 
SMI_NOINTEREST Hook should not be passed the message(s). 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinSetClassMsgInterest -55, WinSetHook -57 


NOTES 


A program can install a MsgControlHook to intercept messages. This 
function calls that hook. 
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@ WinSetMsgMode 


Sets the mode for a message control hook procedure. 


SYNTAX 
BOOL WinSetMsgMode (HAB had, PSZ pszClassname, LONG (Control) 


PARAMETERS 

hab - input 

Anchor block handle. 

pszClassname - input 

The name of the class for which to set the message mode. 
[Control - input 

One of the following values: 


SMD_ DELAYED Messages may be delayed. 
SMD_IMMEDIATE Messages should be processed immediately. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinSetHook -57 | 


NOTES 


A program can install a MsgControlHook to intercept messages. This 
function calls that hook. 





@ WinSetSynchroMode 


Sets the mode of the message control hook procedure. 


SYNTAX 
BOOL WinSetSynchroMode (HAB hab, LONG [Mode) 
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PARAMETERS 

hab - input 

Anchor block handle. 
LMode - input 

One of the following values: 


SSM_ASYNCHRONOUS Messages are asynchronous. 
SSM_MIXED Messages are synchronous or asynchronous. 
SSM_SYNCHRONOUS Messages are synchronous. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_-HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinSetHook -57 


NOTES 


A program can install a MsgControlHook to intercept messages. This 
function calls that hook. 





WinSetWindowThunkProc 





Assigns a thunk procedure for a window. 


SYNTAX 
BOOL WinSetWindowThunkProc (HWND hwnd, PFN p/n) 


PARAMETERS 

hwnd - input 

The handle of the window for which to set the thunk procedure. 

pfn - input 

Pass the address of the function that you wish to assign as the thunk 
procedure for this window. 
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RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINTHUNKAPI 


SEE ALSO 


WinQueryClassThunkProc -46, WinQueryWindowThunkProc -52, 
WinSetClassThunkProc -56, WinQueryWindowModel -51 


NOTES 


When a 16-bit program passes a message containing pointers to a 32- 
bit program, the pointers must be converted from 16-bit to 32-bit con- 
vention. 32-bit convention. You can call this function to set the func- 
tion that converts pointers for all windows of a given class. The 
prototype for the thunk procedure is: 


MRESULT ThunkProc (HWND hwnd, USHORT usMsg, MPARAM 
mpl, MPARAM mp2, PFNWP p/nwp) 

hwnd 

The handle of the 32-bit window procedure. 

usMsgID 

The message identifier (should be greater than WM_USER). 

mp1 

The first message parameter. 

mp2 

The second message parameter. 

bfnwp 

The address of the 32-bit window procedure. 


The thunk function should convert the message parameters and then 
call the 32-bit window procedure. The thunk function must also con- 
vert any return values as required. If the the thunk procedure is called 
with a message identifier it does not recognize, it should call the 32-bit 
window procedure with usMsg set to zero, and mpl and mp2 un- 
changed. 





WinStartTimer 


Schedules a periodic message. 
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SYNTAX 


ULONG WinStartTimer (HAB hab, HWND hwnd, ULONG idTimer, 
ULONG wlTimeout) 


PARAMETERS 

hab - input 

Anchor block handle. 

hwnd - input 

The handle of the window that should receive the WM_TIMER mes- 


sage. You can pass NULLHANDLE for this argument, in which case 
PM posts the message to the queue associated with the calling thread. 


id Timer - input 

The ID PM should assign to the timer. This value should be less than 
TID_USERMAX, which is defined in PMWIN.H. 

ulTimeout - input 

The timer’s interval in milliseconds. The maximum interval allowed is 
65536 milliseconds. (val und v2.11, v3 3 Wher cllow ,EFFFFEEF ) 


RETURNS 


If you pass NULLHANDLE for hwnd, this function returns a timer ID, 
or 0 if the call failed. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinStopTimer -74 


NOTES 


This function causes PM to generate a stream of WM_TIMER messages 
and post them to the window (or thread’s) queue. 

Note that the interval is not guaranteed to be accurate: If the pro- 
gram has higher priority messages in its queue, or is slow to dequeue 
messages, the actual interval may be greater than the specified interval. 
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@ WinStopTimer 
Stops a periodic message. 


SYNTAX 
BOOL WinStopTimer (HAB hab, HWND hwnd, ULONG idTimer) 


PARAMETERS 

hab - input 

Anchor block handle. 
hwnd - input 


Handle of the window that is receiving the timer messages, or NULL- 
HANDLE. 


tdTimer - input 
The timer identity assigned in WinStartTimer. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinStartTimer -72 





@ WinWaitEventSem 





Waits on an event semaphore or a sent message. 


SYNTAX 
ULONG WinWaitEventSem (HEV hev, ULONG wlTimeout) 


PARAMETERS 
hev - input 
A handle to an event semaphore created with DosCreateEventSem. 
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ulTimeout - input 


The maximum number of milliseconds to wait before returning a 
time-out error. Pass SEM_INDEFINITE_WAIT for no time-out or SEM_ 
IMMEDIATE_RETURN to poll the semaphore. 


RETURNS 


0 -NO ERROR 6 - INVALID_HANDLE 
640 - TIMEOUT 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 


WinWaitMuxWaitSem -76, WinSendMsg -54, 
WinRequestMutexSem -53 


NOTES 


This function lets a window procedure wait for either a sent message 
from another process/thread or for an event semaphore to be posted. 





WinWaitMsg 
Lets a program wait for a specific message or range of messages. 


SYNTAX 
BOOL WinWaitMsg (HAB hab, ULONG ulFirst, ULONG ulLast) 


PARAMETERS 

hab - input 

Anchor block handle. 
ulFirst - input 

First message identifier. 
ulLast - input 

Last message identifier. 


RETURNS 
TRUE if successful, FALSE otherwise. 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinGetMsg -39 


NOTES 


This function lets a thread wait for a message to arrive in the message 
queue associated with the anchor block. This call will wait until a mes- 
sage arrives with an identifier between wilFirst and ulLast. See 
WinGetMsg for more information on message filtering. 





@® WinWaitMuxWaitSem 





Waits on a list of semaphores or a sent message. 


SYNTAX 

ULONG WinWaitMuxWaitSem (HMUX hmux, ULONG wlTimeout, 
PLONG pUser) 

PARAMETERS 


hmux - input 

The handle of a multiple-wait semaphore created with DosCreateMux- 
WaitSem. 

ulTimeout - input 

The maximum number of milliseconds to wait before returning a tim- 
eout error. Pass SEM_INDEFINITE_WAIT for no time-out or SEM_IM- 
MEDIATE_RETURN to poll the semaphore. 

pUser- output 

Pass the address of a LONG to which this function writes the user field 
from the MUX-wait semaphrase. 


RETURNS 


0 -NO ERROR 6 - INVALID _ HANDLE 
640 - TIMEOUT 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 
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SEE ALSO 
WinWaitEventSem -74, WinSendMsg -54 


NOTES 


A multiple-wait semaphore is a list of semaphores, each created with 
DosCreateEventSem or DosCreateMutexSem. This function lets a win- 
dow procedure wait for either a sent message from another 
process/thread or for one of the semaphores in the list to be posted or 
released. 
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< though a typical Presentation Manager desktop contains many 
windows, there is only one keyboard. When the user presses a key, 
PM must route any messages from that event to only one of the win- 
dows on the screen—the focus window. Focus applies only to keystroke 
messages; PM normally routes mouse event messages to the window 
underneath the mouse pointer. PM passes keystroke events as WM_ 
CHAR messages, mouse events as WM_BUTTONIDOWN, WM_BUTTON- 
1UP, WM_BUTTONIDBLCK, or WM_MOUSEMOVE. There are equiva- 
lent down, up, and double-click messages for the the second and third 
mouse buttons. 

To help the user know which window will receive the keystrokes, 
a window can display a text entry cursor when it gains the focus, and 
destroy the cursor when the window loses the focus. For example, an 
entryfield window displays a flashing vertical bar cursor, while a push- 
button draws a dashed border around its text. A window receives 
the WM_SETFOCUS message when it gains or loses the focus—PM sets 
the second message parameter to TRUE when the window gains the 
focus, FALSE when it loses the focus. The window may also move the 
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text entry cursor as the user enters data or clicks the mouse within the 
window. 

The functions described in this section allow a program to manip- 
ulate the focus and the text entry cursor. 


Active Window (vs.) Focus Window 


The frame window that contains the focus window is called the active 
window. Normally, the focus window is a child of a frame, for example, 
a button on dialog box or the client window in a standard window. The 
active frame will send a message to its title bar causing it to adopt the 
system-wide active window title bar color; the frame will also draw its 
own border in the active window border color. This makes it easier for 
the user to find the focus window—the user can easily determine 
which is the active window and then locate the focus window within the 
active window. The active window will also normally be “on top” of the 
rest of the windows on the desktop. 


Focus Change Sequence 


When the user (or a program) requests a focus change, PM passes mes- 
sages to the window losing the focus and the window gaining the focus. 
It’s instructive to follow a typical focus change sequence to help un- 
derstand the process. Consider two standard windows on the desktop, 
one a word processor, one a spreadsheet. Imagine that the spreadsheet 
is the active window and the user clicks on the client window in the 
word processor. The word processor client will receive the WM_BUT- 
TONIDOWN message—assume that it passes this message to the de- 
fault window procedure, which issues: 


WinSetActiveWindow ( HWND_DESKTOP, hwnd ); 


This function calls WinFocusChange, which sends the current ac- 
tive frame window (the spreadsheet) the WM_FOCUSCHANGE mes- 
sage. The spreadsheet frame responds to this message by sending its 
client window WM_ACTIVATE, WM_SETSELECTION, and WM_SETFO- 
CUS because the client is losing the focus. Control then returns to the 
WinFocusChange function (running in the word processor), which 
sends WM_QUERYFOCUSCHAIN to the frame window to determine 
the new focus window's handle, in this case, the word processor client 
window. WinFocusChange then sends WM_FOCUSCHANGE to the 
word processor client. Assume that the client window procedure passes 
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this message to the default window procedure, which passes it on to 
the client’s parent—the frame window. This word processor frame win- 
dow then sends its client WM_SETFOCUS, WM_SETSELECTION, and 
WM_ACTIVATE, telling the client that it is gaining the focus. 

A window can process WM_SETFOCUS to create or destroy a text 
entry cursor and process WM_SETSELECTION to highlight or unhigh- 
light any selected text or graphics. Note that PM only sends WM_SET- 
SELECTION if it determines that the window is losing focus to a win- 
dow not owned by the first window; if the user displays a dialog in the 
same program, the text or graphics will stay selected. 


Virtual Keys 


Because OS/2 will eventually run on many different hardware plat- 
forms, PM passes keystroke values in a hardware-independent fashion 
using virtual key codes that correspond to common nondata keys like 
the F2 key and are defined in PMWIN.H, for example VK_F2. The key- 
board device driver translates raw keystroke data—for example, a 
hardware scan code—into the virtual key constants. Data keys, for ex- 
ample the a key, are translated into code points based on the current 
national language. For example, in United States English, the lower- 
case a character is reported as 0x61. 
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WinAlarm sounds an alarm (pg 81). 

WinCreateCursor creates a text entry cursor (pg 82). 
WinDestroyCursor deletes a text entry cursor (pg 84). 
WinEnablePhysInput enables or disables the mouse and keyboard 
(pg 84). 

WinEnableWindow sets or clears a window’s enabled flag (pg 85). 
WinEnableWindowUpdate prevents or allows a window to paint (pg 86). 
WinFlashWindow flashes a frame window (pg 87). 

WinFocusChange changes the input focus (pg 88). 

WinGetKeyState retrieves a key’s state at the time of the last message 
(pg 89). 

WinGetPhysKeyState retrieves a key’s state at the current time (pg 91). 
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WinIsPhysInputEnabled determines if input is locked via WinEnable- 
PhysInput (pg 92). 

WinIsThreadActive determines that the calling thread owns the active 
window (pg 92). 

WinIsWindowEnabled retrieves a window’s enabled flag (pg 93). 
WinQueryActiveWindow retrieves the active frame window’s handle 


(pg 94). 
WinQueryCapture retreives the mouse capture window’s handle 
(pg 94). 
WinQueryCursorInfo retrieves information about a text entry cursor 
(pg 95). 


WinQueryFocus retrieves the focus window’s handle (pg 96). 
WinSetActiveWindow assigns the active frame window (pg 97). 
WinSetCapture lets a window receive all mouse messages (pg 98). 
WinSetFocus changes the input focus (pg 99). 
WinSetKeyboardStateTable sets or retrieves key states (pg 100). 
WinShowCursor shows or hides a text entry cursor (pg 101). 





WinAlarm 





Sounds an alarm. 


SYNTAX 
BOOL WinAlarm (HWND hwndDesktop, ULONG  ulType) 


PARAMETERS 

hwndDesktop - input 

Desktop window handle (HWND_DESKTOP). 

ulType - input 

The alarm to sound. Must be one of the following values: WA_ERROR, 
WA_NOTE, WA_WARNING. 

The frequency and duration of these alarms are system values that you 
can set with WinSetSysValue and retrieve with WinQuerySysValue. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID _ 0Ox1019 - PMERR_INVALID _ 
HWND FLAG 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 


SEE ALSO 
WinSetSysValue -356, WinQuerySysValue -342 


NOTES 


This function will not sound the alarm if the system value SV_ALARM 
is off. You can set that value with WinSetSysValue and retrieve it with 
WinQuerysysValue. 





@ WinCreateCursor 





Creates a text entry CurSOr. 


SYNTAX 


BOOL WinCreateCursor (HWND hwnd, LONG x, LONG y, LONG 
cx, LONG cy, ULONG fl, PRECTL prc!) 


PARAMETERS 

hwnd - input 

The window that is creating the cursor. 

x - input 

The x-coordinate in pixels of the cursor’s lower left relative to the win- 
dow’s lower left corner. 

y - Input 

The y-coordinate in pixels of the cursor’s lower left relative to the win- 
dow’s lower left corner. 


cx - input 

The cursor’s width, in pixels. 
cy - input 

The cursor’s height, in pixels. 
fl- input 


Any combination of the following flags: 


CURSOR _FLASH_ PM should flash the cursor. 

CURSOR_FRAME The cursor will be a rectangle. 

CURSOR_HALFTONE PM will draw every other pixel of the cursor 
to create a halftone, or grayed cursor. Cannot be combined with 
CURSOR_SOLID. 
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CURSOR_SETPOS Causes PM to ignore the cx and cy arguments 
and other style flags and simply change the cursor’s position. You 
can only use this flag if the cursor is already created without this flag. 

CURSOR SOLID PM will draw the cursor with a solid line. This is 
the default. Cannot be combined with CURSOR_HALFTONE. 


prel - input 

Pass the address of a RECTL structure that this function uses as a clip- 
ping rectangle for the cursor. Pass NULL to have the cursor clipped 
only to the window. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_ 0x1019 - PMERR_INVALID_ 
HWND FLAG 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCURSORS 


SEE ALSO 


WinDestroyCursor -84, WinShowCursor -101, 
WinQueryCursorInfo -95, WinScrollWindow -129, 
WinSetSysValue -356 


NOTES 


A window that accepts keystrokes should use this function to display a 
text entry cursor when it gains the focus, and should destroy the cur- 
sor when it loses the focus. ‘The window can determine when it gains or 
loses the focus by processing the WM_SETFOCUS message and exam- 
ining the second message parameter, which contains ‘TRUE when the 
window gains the focus, FALSE when it loses the focus. 

To move the cursor, you can call this function and specify the CUR- 
SOR_SETPOS flag. 

This function creates the cursor invisibly. You can show the cursor 
with WinShowCursor. 

If a window with a cursor calls WinScrollWindow, that function 
changes the cursor position as specified by the scroll. 

You can pass zero for either the cx or cy arguments, but not both. 
If you pass zero for the width, this function uses the system border 
width (see WinSetSysValue). If you pass zero for the height, this func- 
tion uses the system border height. 
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@® WinDestroyCursor 


Deletes a text entry cursor. 


SYNTAX 
BOOL WinDestroyCursor (HWND hwnd) 


PARAMETERS 
hwnd - input 
The window containing the cursor. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCURSORS 


SEE ALSO 
WinCreateCursor -82, WinShowCursor -101 


NOTES 


A window typically calls this function during the WM_SETFOCUS mes- 
sage, when the second message parameter is FALSE indicating that the 
window is losing the input focus. 





@ WinEnablePhysinput 


Enables or disables the mouse and keyboard. 


SYNTAX 
BOOL WinEnablePhysInput (HWND hwndDeskiop, BOOL /Enable) 


PARAMETERS 


hwndDesktop - input 
The desktop window handle (HWND_DESKTOP). 
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fEnable - input 
Pass ‘TRUE to enable the mouse and keyboard, FALSE to disable them. 


RETURNS 


The previous enable state. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WININPUT 


SEE ALSO 
WinEnableWindow -85, WinEnableWindowUpdate -86 


NOTES 

This function prevents the system from queuing keyboard and mouse 
messages. Note: It is dangerous to issue this function to disable input 
and then wait for user input before enabling input. 





WinEnableWindow 





Sets or clears a window’s enabled flag. 


SYNTAX 
BOOL WinEnableWindow (HWND hwnd, BOOL f) 


PARAMETERS 

hwnd - input 

The window to enable or disable. 

f- input 

Pass TRUE to enable the window, FALSE to disable it. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinEnableWindowUpdate -86, WinIsWindowEnabled -93, 
WinAlarm -81, WinEnablePhysInput -84 


NOTES 


Every window has a flag in its PM-internal window data structure that 
this flag sets or clears. You can query this flag’s state with Winls- 
WindowEnabled. PM will not route any mouse messages to a disabled 
window, but will issue WinAlarm to sound the alarm. A disabled window 
can have the focus and can receive keystroke messages. However, most 
windows, for example buttons, sound the alarm when they receive key- 
strokes in the disabled state. 

A disabled window still can receive messages including timer and 
paint messages. Most windows draw themselves differently if they are 
disabled. For example, a disabled button draws its text in halftone. 

When this function changes the enable state of a window, it sends 
the window the WM_ENABLE message so the window can change its 
appearance. 

If you disable a window with descendants, PM also disables the de- 
scendant windows, but they do not receive the WM_ENABLE message. 





WinEnableWindowUpdate 


Prevents or allows a window to paint. 


SYNTAX 
BOOL WinEnableWindowUpdate (HWND hwnd, BOOL /) 


PARAMETERS 
hwnd - input 
The window to enable or disable from painting. 


f- input 
Pass TRUE to enable the window to paint, FALSE to disable. 
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RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinShowWindow -319, WinEnableWindow -85, 
WinInvalidateRect -138 


NOTES 


A program can use this function to temporarily prevent a window from 
painting. For example, you can issue this call with a FALSE argument 
before adding items to a listbox window and then issue it with TRUE 
after adding the items. This will speed up adding the items since the 
listbox will not repaint as each item is added. You should invalidate the 
entire window when finished. 

This function is essentially the same as WinShowWindow, in that it 
sets or clears the window's internal WS_VISIBLE style flag. ‘The func- 
tions differ in that this function does not hide a window nor show it; it 
simply prevents the window’s output from being passed to the window. 

If this function causes the WS_VISIBLE flag to change (if you pass 
FALSE on a visible window), the window receives the WM_SHOW mes- 
sage. 





WinFiashWindow 


Flashes a frame window. 


SYNTAX 
BOOL WinFlashWindow (HWND hwnd, BOOL f) 


PARAMETERS 
hwnd - input 
The handle of the frame window to flash. 


f- input 
Pass TRUE to start the window flashing, FALSE to stop it. 
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RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


OX001 - PMERR_ INVALID _HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINFRAMEMGR 


SEE ALSO 
WinAlarm -81 


NOTES 


This function passes the WM_FLASHWINDOW message to the indi- 
cated window. Frame windows (WC_FRAME class) respond to this mes- 
sage by flashing their title bar child window and sounding the alarm 
for the first five flashes. 

Since flashing and beeping are quite intrusive, you should not is- 
sue this call unless something is very wrong. However, it does allow a 
nonactive window to get the user’s attention. 





@ WinFocusChange 


Changes the input focus. 


SYNTAX 

BOOL WinFocusChange (HWND hwndDeskiop, HWND hwnd, 
ULONG /!) 

PARAMETERS 


hwndDesktop - input 

The desktop window handle (HWND_DESKTOP). 

hwnd - input 

The window to which to change the focus. 

fl- input 

A combination of the following flags: 

FC_NOBRINGTOPFIRSTWINDOW Do not force the first frame 
window to the the top of the Z-order. This flag is the same as 
FC_NOSETFOCUS. 
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FC_NOBRINGTOTOP Do not force any window to the the top of 
the Z-order. This flag is the same as FC_NOLOSEFOCUS. 

FC_NOLOSEACTIVE Do not send WM_ACTIVATE to the window 
losing the focus. 

FC_NOLOSEFOCUS Do not send WM_SETFOCUS to the window 
losing the focus. 

FC_NOLOSESELECTION Do not send WM_SETSELECTION to the 
window losing the focus. 

FC_NOSETACTIVE Do not send WM_ACTIVATE to the window 
gaining the focus. 

FC_NOSETFOCUS Do not send WM_SETFOCUS to the window 
gaining the focus. 

FC_NOSETSELECTION Do not send WM_SETSELECTION to the 
window gaining the focus. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WININPUT 


SEE ALSO 


WinSetFocus -99, WinQueryFocus -96, WinSetActiveWindow -97, 
WinQueryActiveWindow -94 


NOTES 


This function causes a focus change sequence. Most programs use 
WinSetActiveWindow or WinSetFocus instead of this function—both 
of those functions internally call this function. 

The focus change sequence is described at the beginning of this 
chapter. 





WinGetKeyState 


Retrieves a key’s state at the time of the last message. 
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SYNTAX 
LONG WinGetKeyState (HWND hwndDeskiop, LONG [Key) 


PARAMETERS 

hwndDesktop - input 

The desktop window’s handle (HWND_DESKTOP). 

[Key - input 

Store the virtual key value to query in the lower 16 bits, zero in the 16 
most significant bits. 


RETURNS 


A combination of the following values: 


0x0001 ‘The key has been pressed an odd number of times since the 
system was booted. 

0x8000 ‘The key was down when the last message was dequeued from 
the message queue. 


Possible returns from WinGetLastError: 


Oxl001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WININPUT 


SEE ALSO 
WinGetPhysKeyState -91, WinEnablePhysInput -84 


NOTES 


This function lets a program determine if a key was depressed at the 
time a message was dequeued. For example, the following uses this 
function to determine if the Control key was pressed when the user 
clicked the first mouse button: 


case WM_BUTTONI1DOWN: 
1f ( WinGetKeyState ( HWND_DESKTOP, VK_CTRL ) & 0x8000 ) 
{ 
// ctrl key down 
} 
else 
{ 
// ctrl key not down 
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NOTES 


To determine if a key is currently down (not at the time of the last mes- 
sage), use WinGetPhysKeyState. 





WinGetPhysKeyState 


Retrieves a key’s state at the current time. 


SYNTAX 
LONG WinGetPhysKeyState (HWND hwndDesktop, LONG ([Scan) 


PARAMETERS 


hwndDeshtop - input 

The desktop window’s handle (HWND_DESKTOP). 

lScan - input 

Store the key’s hardware scan code value to query in the lower 16 bits, 
zero in the 16 most significant bits. 


RETURNS 

A combination of the following values: 

0x0001 ‘The key has been pressed an odd number of times since the 
system was booted. 

0x0002 ‘The key has been pressed since the last time this function was 


issued. 
0x8000 ‘The key is currently down. 


Possible returns from WinGetLastError: 


0Ox1001 - PMERR_ INVALID _HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WININPUT 


SEE ALSO 
WinGetKeyState -89 


NOTES 


This function calls the keyboard device driver to determine the key’s 
state. It doesn’t attempt to synchronize with message processing, so 
this function is unreliable if you want to determine if a key was pressed 
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while processing another user input message. In that situation, you 
should call WinGetKeyState. 

This function is also somewhat nonportable, since the hardware 
scan code value will vary on different hardware platforms. 





@ WinlsPhysinputEnabled 


Determines if input is locked via WinEnablePhysInput. 


SYNTAX 
BOOL WinlIsPhysInputEnabled (HWND hwndDesktop) 


PARAMETERS 


hwndDeshtop - input 
The desktop window’s handle (HWND_DESKTOP). 


RETURNS 


TRUE if input is enabled, FALSE if it is disabled. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WININPUT 


SEE ALSO 
WinEnablePhysInput -84 





@® WinlsThreadActive 





Determines if the calling thread that owns the active window. 


SYNTAX 
BOOL WinIsThreadActive (HAB had) 


PARAMETERS 
hab - input 
Calling thread’s anchor block handle. 
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RETURNS 


TRUE if thread owns the currently active frame window, FALSE if not. 
Possible returns from WinGetLastError: 


Ox104a - PMERR_INVALID_Hab 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinQueryActiveWindow -94, WinSetActiveWindow -97 





WinlsWindowEnabled 


Retrieves a window's enabled flag. 


SYNTAX 
BOOL WinIsWindowEnabled (HWND hwnd) 


PARAMETERS 
hwnd - input 
The window to query. 


RETURNS 


TRUE if window is enabled, FALSE if it is not. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinEnableWindow -85, WinEnableWindowUpdate -86 


NOTES 


Every window has a flag in its PM-internal window data structure that 
this function queries. See WinEnableWindow for a discussion of how 
PM uses this flag. 
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@ WinQueryActiveWindow 


Retrieves the active frame window’s handle. 


SYNTAX 
HWND WinQueryActiveWindow (HWND hwndParent) 


PARAMETERS 


hwndParent - input 
The parent of the active window or the desktop window’s handle 


(HWND_DESKTOP). 
RETURNS 


The active frame window’s handle, or NULLHANDLE. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_ INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinSetActiveWindow -97, WinQueryFocus -96 


NOTES 


This function lets you determine which frame window is active in a hi- 
erarchy of frame windows. To determine the top-level active frame win- 
dow on the desktop, pass HWND_DESKTOP as hwndParent. 





@ WinQueryCapture 


Retrieves the mouse capture window's handle. 


SYNTAX 
HWND WinQueryCapture (HWND hwndDeskiop) 


PARAMETERS 


hwndDesktop - input 
The desktop window’s handle (HWND_DESKTOP). 
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RETURNS 


The handle of the window that has captured the mouse, or NULL- 
HANDLE if no window has captured the mouse. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinSetCapture -98 


NOTES 


A window can issue WinSetCapture so that PM passes all mouse mes- 
sages to that window, regardless of the mouse pointer position. This 
function retrieves the window handle of any window that has current 
mouse capture. 





WinQueryCursorInfo 


Retrieves information about a text entry cursor. 


SYNTAX 

BOOL WinQueryCursorInfo (HWND hwndDeskitop, PCURSORINFO 
pcrst) 

PARAMETERS 


hwndDeshtop - input 

The desktop window’s handle (HWND_DESKTOP). 

perst - output 

Pass the address of a CURSORINFO structure that this function will 
fill in: 


typedef struct _CURSORINFO /* csri */ 
{ 

HWND hwnd; 

LONG x; 

LONG y; 

LONG Cx; 

LONG cy; 
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ULONG fs; 
RECTL rclClip;: 
} CURSORINFO; 


hwnd ‘The handle of the window that created the cursor. 

x The cursor’s x-coordinate in pixels, relative to the window’s lower 
left corner. 

y The cursor’s y-coordinate in pixels, relative to the window’s lower 
left corner. 

cx The cursor’s width in pixels. 

cy The cursor’s height in pixels. 

fs A combination of the following flags that describe the cursor: 

CURSOR _ FLASH PM flashes the cursor. 

CURSOR_FRAME The cursor is a rectangle. 

CURSOR_HALFTONE PM draws every other pixel of the cursor to 
create a halftone, or grayed cursor. 

CURSOR_SOLID PM draws the cursor with a solid line. 

rclClip Contains the coordinates of a rectangle that PM uses to clip 
the cursor. If this rectangle was specified as NULL in WinCreate- 
Cursor, all of the fields in the structure will be zero. 


RETURNS 


TRUE if successful, FALSE if there is no cursor. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file pmwin.h Define: INCL_WINCURSORS 


SEE ALSO 
WinCreateCursor -82, WinShowCursor -101, WinDestroyCursor -84 


NOTES 


This function retrieves the cursor information that the creator speci- 
fied in WinCreateCursor. 





@ WinQueryFocus 


Retrieves the focus window’s handle. 
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SYNTAX 
HWND WinQueryFocus (HWND hwndDesktop) 


PARAMETERS 


hwndDeskhtop - input 
The desktop window’s handle (HWND_DESKTOP). 


RETURNS 


The current focus window’s handle, or NULLHANDLE if no window 
has the focus. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WININPUT 


SEE ALSO 
WinSetFocus -99 





WinSetActiveWindow 





Assigns the active frame window. 


SYNTAX 
BOOL WinSetActiveWindow (HWND hwndDeskitoph, HWND hwnd) 


PARAMETERS 


hwndDesktop - input 

The desktop window’s handle (HWND_DESKTOP). 
hwnd - input 

The handle of the window to activate. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinFocusChange -88, WinSetFocus -99, 
WinQueryActiveWindow -94 


NOTES 


This function internally calls WinFocusChange to change the focus 
and the active window. If the hwnd argument doesn’t refer to a frame 
window, this function queries up the tree of parent windows to find a 
frame window. 

See the beginning of this section for a description of the focus 
change sequence. 





@ WinSetCapture 


Lets a window receive all mouse messages. 


SYNTAX 
BOOL WinSetCapture (HWND hwndDeskiop, HWND hwnd) 


PARAMETERS 


hwndDesktop - input 

The desktop window’s handle (HWND_DESKTOP). 

hwnd - input 

The handle of the window to which to assign the focus. Pass NULL- 
HANDLE to release the focus. Pass HWND_THREADCAPTURE to as- 
sign capture to the calling thread, rather than a window. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WININPUT 
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SEE ALSO 
WinQueryCapture -94, WinGetMsg -39, WinPeekMsg -43 


NOTES 


Normally, PM passes mouse messages to the window underneath the 
mouse pointer’s hot spot. This function lets a window override this 
routing and cause PM to pass all mouse messages to the window, re- 
gardless of the pointer’s position. When capture is in effect, PM speci- 
fies the mouse message coordinates in the normal fashion (unless you 
specify HWND_THREADCAPTURE) that is, in pixels, relative to the 
window's lower left corner. Note that when the mouse is captured, the 
mouse coordinates can be negative. 

If you specify HWND_THREADCAPTURE, then when either 
WinGetMsg or WinPeekMsg dequeues a mouse message, the QMSG 
structure has hwnd set to NULLHANDLE, and the coordinates are in 
pixels, relative to the desktop’s lower left corner. 

To release the mouse capture, issue this function again with hwnd 
as NULLHANDLE. 

A window should only capture the mouse in response to a user- 
input message, for example a button down message. Also, do not cre- 
ate a dialog or message box while the mouse is captured. 





WinSetFocus 





Changes the input focus. 


SYNTAX 
BOOL WinSetFocus (HWND hwndDesktop, HWND hwnd) 


PARAMETERS 


hwndDesktop - input 

The desktop window’s handle (HWND_DESKTOP). 

hwnd - input 

The handle of the window to which to set the focus. Pass HWND_DESK- 
TOP to assign no window the focus. 


RETURNS 
TRUE if successful, FALSE otherwise. 
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Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WININPUT 


SEE ALSO 


WinFocusChange -88, WinSetActiveWindow -97, 
WinQueryFocus -96 


NOTES 


This function internally calls WinFocusChange to change the focus. 
See the beginning of this section for a description of the focus change 
sequence. 





@ WinSetKeyboardStateTable 


Sets or retrieves key states. 


SYNTAX 

BOOL WinSetKeyboardStateTable (HWND hwndDesktop, PBYTE ad, 
BOOL /Set) 

PARAMETERS 


hwndDesktop - input 

The desktop window’s handle (HWND_DESKTOP). 

ab - input/output 

Pass the address of an array containing 256 bytes. If you pass FALSE for 
the /Set argument, this function fills in the array. If you pass TRUE, this 
function sets the key states from this table. 

fSet- input 

Pass TRUE to set key states, FALSE to retrieve key states. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


Keystrokes and Focus 101 


OTHER INFO 
Include file: pmwin.h Define: INCL_WININPUT 


SEE ALSO 
WinGetKeyState -89, WinGetPhysKeyState -91 


NOTES 


PM maintains an internal table of states for all 256 virtual keys. A pro- 
gram can query this state information for a single key with WinGet- 
KeyState, and retrieve the entire table with this function. For each key, 
the state byte contains the following bits. 


0x80 Set to one if the key was down at the time of the last message. 
0x01 Set to one if the key has been pressed an odd number of times 
since the system was booted. 


You can use the VK_xxx virtual key constants defined in PMWIN.H 
as indexes into this array. 

To change a single key’s state, you must first query the table, 
change the key’s entry in the array, and then set the table. This function 
does not actually change the keyboard hardware, but simply updates 
the internal array so that the next WinGetKeyState or WinSetKey- 
boardStateTable use the new value. 





WinShowCursor 





Shows or hides a text-entry cursor. 


SYNTAX 
BOOL WinShowCursor (HWND hwnd, BOOL f) 


PARAMETERS: 
hwnd - input 
The window containing the cursor. 


f- input 
Pass TRUE to show the cursor, FALSE to hide it. 


RETURNS 
TRUE if successful, FALSE otherwise. 
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Possible returns from WinGetLastError. 


0Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INGCL_WINCURSORS 


SEE ALSO 


WinCreateCursor -82, WinDestroyCursor -84, 
WinQueryCursorInfo -95 


NOTES 


A window can use this function to temporarily hide the cursor. You 
should not use this function when you lose the focus, but instead call 
WinDestroyCursor and re-create the cursor with WinCreateCursor 
when you again gain the focus. 

PM maintains a hide count for the cursor. Passing FALSE to this 
function increments the count; TRUE decrements it. If the count is 
zero, PM displays the cursor. This function will not decrement the hide 
count below zero. 





Presentation 
Spaces and 
Device Contexts 





Bo a PM program can send output to a graphical device such as 
a display window or a printer, it must first obtain handles to a pre- 
sentation space and a device context. The presentation space handle 
acts as the target for graphical output calls, while the device context is 
an internal data structure that encapsulates a device driver. After re- 
trieving the two handles, the PM program must connect or associate the 
presentation space and the device context to form a pathway to the ac- 
tual device. 

Some of the functions described in this section hide some of the 
details of the presentation space and device context. For example, 
WinBeginPaint retrieves a presentation space handle that’s already as- 
sociated with the current screen device context. 
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Presentation Space Types 


Presentation Manager supports the following kinds of presentation 
spaces: 


cached-micro Handles retrieved by WinGetPS, WinBeginPaint, and 
WinGetScreenPS. PM preallocates a number of cached-micro pre- 
sentation spaces that are shared among all windows. Since these are 
shared, a program must release the handle back to PM before re- 
turning from the message in which the handle was retrieved. Also, 
cached-micro presentation spaces are always associated with the cur- 
rent screen device—you cannot use one to print. Furthermore, 
some GPI calls are only valid on a normal PS (for example, 
GpiDrawChain). The advantage of this type is that because they are 
preallocated, the functions that retrieve the handle execute quickly. 

micro Created by GpiCreatePS. You can associate a micro PS with any 
device context and hold it for the life of your program. Its disadvan- 
tage is that PM must allocate the storage for each PS (no cache), so 
GpiCreatePS may take a long time to execute, and if you hold the 
PS for your program’s life, you are “wasting” its memory when it’s 
not actually being used. In addition, some GPI calls are only valid on 
a normal PS (for example, GpiDrawChain). 

normal Created by GpiCreatePS. You can associate a normal PS with 
any device context and hold it for the life of your program, so it has 
the same advantages and disadvantages as the micro PS except that 
all GPI calls work on a normal PS. In addition, the normal PS is the 
only type that lets you change its association dynamically with 
GpiAssociate. 

Note: GPI functions are not covered in this book. 


Presentation Space and Device Context Functions 





WinBeginPaint initializes a window procedure’s WM_PAINT process- 
ing (pg 105). 
WinEndPaint concludes a window procedure’s WM_PAINT processing 


(pg 106). 
WinGetClipPS retrieves a cached-micro PS with invalid region clipping 


established (pg 107). 
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WinGetPS retrieves a cached-micro PS without invalid region clipping 
(pg 108). 

WinGetScreenPS retrieves a cached-micro PS clipped to the desktop 
(pg 109). 

WinOpenWindowDC opens a window device context (pg 110). 
WinQueryWindowDC retrieves the handle for a window device con- 
text (pg 111). 

WinReleasePS releases a PS handle retrieved with WinGetClipPS, 
WinGetPS, or WinGetScreenPS (pg 112). 

WinWindowFromDC retrieves the window handle of the window cou- 
pled to a window device context (pg 112). 





WinBeginPaint 
Initializes a window procedure’s WM_PAINT processing. 


SYNTAX 
HPS WinBeginPaint (HWND hwnd, HPS hps, PRECTL prcl) 


PARAMETERS 

hwnd - input 

The handle of the window to paint. 

hps - input 

An existing presentation space handle. To cause this function to re- 
trieve a cached-micro PS handle, pass NULLHANDLE for this argu- 
ment. 

prel - output 

Pass the address of a RECTL data structure. Returns the coordinates of 
the smallest rectangle that bounds the window’s invalid region. If you 
don’t need this rectangle, pass NULL for this argument. 


RETURNS 


NULLHANDLE- An error occurred. 

Other - A presentation space handle. If you passed an input PS handle 
in the second argument, the function returns the same handle here. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_ INVALID _ 0x207f - PMERR_INV_ 
HWND HPS 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinEndPaint -106, WinGetPS -108 


NOTES 


This function performs the following tasks: 

@ It optionally returns a cached-micro PS handle from the pool preal- 
located by PM. 

@ It validates or clears the window's invalid region, thus preventing 
any further WM_PAINT messages until the window is again invalid. 

@ It optionally returns the coordinates of the invalid reqion’s bound- 
ing rectangle. 

@ It applies a clip to the presentation space so that any output via that 
PS handle is clipped to the invalid region. 

@ It hides any text entry cursor, tracking rectangle and mouse pointer 
(WinEndPaint restores them). 


EXAMPLE 


case WM_PAINT: 
{ 
HPS hps; // cached-micro PS handle 
RECTL rel; // bounding rectangle 
hps = WinBeginPaint ( hwnd, NULLHANDLE, &rcl ); 
GpiErase ( hps ); 
WinEndPaint ( hps ); 
} 


return 0; 





@ WinEndPaint 





Concludes a window procedure’s WM_PAINT processing. 


SYNTAX 
BOOL WinEndPaint (HPS hps) 
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PARAMETERS 
hps - input 
The presentation space handle used to paint the window. 


RETURNS 


TRUE if successful, FALSE otherwise 
Possible returns from WinGetLastError: 


0x207f - PMERR_INV_HPS 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinBeginPaint -105 


NOTES 


This function terminates the WM_PAINT processing started by Win- 
BeginPaint. It restores the mouse pointer, tracking rectangle, and text 
entry cursor, and also passes any necessary WM_PAINT messages to 
any child windows that have the WS_SYNCHPAINT style. 





WinGetClipPS 


Retrieves a cached-micro PS with invalid region clipping established. 


SYNTAX 
HPS WinGetClipPS (HWND hwnd, HWND hwndClp, ULONG /fiClip) 


PARAMETERS 

hwnd - input 

The handle of the window to paint. 

hwndChip 

A window handle that this function uses along with the clip flags to de- 
termine the clip region. If you specify PSF_CLIPUPWARDS or PSF _ 
CLIPDOWNWARDS, then the following are also valid: 


NULLHANDLE All siblings. 
HWND_BOTTOM The bottom window in a stack of siblings. 
HWND_TOP The top window in a stack of siblings. 
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fiChp - input 

Any combination of the following clipping flags: 

PSF_CLIPCHILDREN Provide a clip region that excludes all child 
windows of the input hwnd. 

PSF_LOCKWINDOWUPDATE Provide clipping so that there is a visi- 
ble region even if WinLockWindowUpdate has blocked output to 
the window. 

PSF_PARENTCLIP Provide a clip region to the bounds of the parent 
of hwnd. Caution: This flag allows a window to draw outside of its 
own boundary. 

PSF_CLIPSIBLINGS Provide a clip region that excludes all siblings of 
the input hwnd. 

PSF_CLIPUPWARDS Provide a clip region that excludes siblings be- 
fore hwndChp. You cannot specify this flag and PSF_CLIPDOWN- 
WARDS. 

PSF_CLIPDOWNWARDS Provide a clip region that excludes siblings 
after hwndClip. You cannot specify this flag and PSF_CLIPUPWARDS. 


NULLHANDLE - An error occurred. 
Other - A cached-micro presentation space handle. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_ INVALID _HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinReleasePS -112 


NOTES 


This function returns a cached-micro PS handle that you must release 
with WinReleasePS before the end of the message in which you ob- 
tained the handle. 





@ WinGetPS 





Retrieves a cached-micro PS without invalid region clipping. 


SYNTAX 
HPS WinGetPS (HWND hwnd) 
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PARAMETERS 
hwnd - input 
The handle of the window to paint. 


RETURNS 


NULLHANDLE- An error occurred. 
Other - A cached-micro presentation space handle. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinReleasePS -112, WinGetClipPS -107, WinGetScreenPS -109 


NOTES 


This function returns a cached-micro PS handle that you must release 
with WinReleasePS before the end of the message in which you ob- 
tained the handle. 

The difference between this function and WinBeginPaint is that 
this function neither affects nor takes into account the window’s in- 
valid region; that is, the presentation space returned by this function is 
not clipped to the window’s invalid region. 





WinGetScreenPS 





Retrieves a cached-micro PS clipped to the desktop. 


SYNTAX 
HPS WinGetScreenPS (HWND hwndDeskiop) 


PARAMETERS 


hwndDesktop - input 
The desktop window’s handle. 


RETURNS 


NULLHANDLE- An error occured 
Other - A cached-micro presentation space handle. 
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Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinReleasePS -112 


NOTES 


This function returns a cached-micro PS handle that you must release 
with WinReleasePS before the end of the message in which you ob- 
tained the handle. 

The origin of the presentation space is the lower left corner of the 
desktop, and there is no clipping applied. 





@® WinOpenWindowDC 


Opens a window device context handle. 


SYNTAX 
HDC WinOpenWindowDC (HWND hwnd) 


PARAMETERS 
hwnd - input 
The handle for the window for which to open the device context. 


RETURNS 


NULLHANDLE- An error occured 
Other - The window device context handle 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 
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NOTES 


When a program issues this function, PM creates a window device con- 
text that is coupled to the input window. This function returns the de- 
vice context handle. A program should not close or destroy the handle 
retrieved with this function. PM deallocates the device context when 
the window is destroyed. 

After calling this function, a program can issue GpiCreatePS to 
create a micro or normal presentation space associated with the win- 
dow device context. 


EXAMPLE 
HDC nae; // window DC 
HPS hps; // micro PS 
SIZEL sizel; // presentation page size 


hdc = WinOpenWindowDC ( hwnd ); 
Sigel cx = sizel.cy = G; 
hps = GpiCreatePS ( hab, hdc, &sizel 
, PU_PELS | GPIA_ASSOC | GPIT_MICRO ); 





WinQueryWindowDC 


Retrieves the handle for a window device context. 


SYNTAX 
HDC WinQueryWindowDC (HWND hwnd) 


PARAMETERS 
hwnd - input 
The handle for the window for which to retrieve the device context. 


RETURNS 


NULLHANDLE- An error occurred 
Other - The window device context handle 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 
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SEE ALSO 
WinOpenWindowDC -110 


NOTES 


A program can call this function to retrieve the window device context 
coupled with a window. Note that this function only returns a device 
context handle if WinOpenWindowDC has previously been issued on 
the window; otherwise it returns NULLHANDLE. 





@ WinReleasePS 





Releases a PS handle retrieved with WinGetClipPS, WinGetPS, or 
WinGetScreenPS. 


SYNTAX 
BOOL WinReleasePS (HPS hps) 


PARAMETERS 

hps - input 

A cached-micro presentation space handle allocated by WinGetClipPS 
(pg 107), WinGetPS (pg 108), or WinGetScreenPS (pg 109). 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


NOTES 


This function releases a cached-micro presentation space back to the 
pool of preallocated presentation spaces. 





@ WinWindowFromDC 





Retrieves the window handle of the window coupled to a window de- 
vice context. 


Presentation Spaces and Device Contexts 113 


SYNTAX 
HWND WinWindowFromDC (HDC hdc) 


PARAMETERS 
hdc - input 
A window device context handle retrieved with WinOpenWindowDC. 


RETURNS 


NULLHANDLE - An error occurred. 
Other-The coupled window handle to the input device context handle. 
Possible returns from WinGetLastError: 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinOpenWindowDC -110 


NOTES 

A program can use this function to retrieve the window handle cou- 
pled to a window device context. Before issuing this function, Win- 
OpenWindowDC must have been issued on the window. 





Window Drawing 
Functions 





M provides a limited number of functions that draw to a presenta- 

tion space. Most of the graphical output functions are part of the 
Graphical Programming Interface (GPI) subsection not covered in 
this book. 


Window Drawing Functions 





WinDrawBitmap draws a bitmap to a window (pg 115). 
WinDrawBorder draws a rectangular border (pg 118). 
WinDrawPointer draws a pointer or an icon (pg 121). 
WinDrawText draws a line of text to a window (pg 122). 
WinFillRect fills the interior of a rectangle with a color (pg 125). 
WinInvertRect inverts the interior of a rectangle (pg 126). 
WinMakePoints initializes a point variable (pg 127). 
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WinRealizePalette loads a logical palette into the physical palette 
(pg 127). 

WinScrolilWindow scrolls the contents of a window (pg 129). 
WinShowTrackRect hides or shows a rectangle that the user can move 
or size (pg 130). 

WinTrackRect draws a rectangle that the user can move or size (pg 131). 





WinDrawBitmap 


Draws a bitmap to a window. 


SYNTAX 


BOOL WinDrawBitmap (HPS hps, HBITMAP him, PRECTL prelSrc, 
PPOINTLpilTarg, LONG [ColorForeground, 
LONG/ColorBackground, ULONG/I) 


PARAMETERS 

hps - input 

The presentation space to which to draw the bitmap. 

hbm - input 

The handle of the bitmap to draw. The bitmap must not be set into a 
presentation space. 

prelSrc - input 

Pass the address of a RECTL that contains the coordinates that de- 
scribe how much of the bitmap to copy to the presentation space. The 
coordinate units are in pixels relative to the lower left of the bitmap. 
Pass NULL to specify the entire bitmap. 

ptlTarg - input 

Pass the address of a POINTL that specifies the position in the target 
presentation space for the lower left of the bitmap. These coordinate 
units are in pixels, relative to the presentation space’s lower left cor- 
ner. If you specify DBM_STRETCH in the fl parameter, this function ex- 
pects you to pass the address of a RECTL instead of a POINTL in this ar- 
gument. The RECTL should contain the coordinates (in pixels) in the 
target presentation space to which this function will draw the bitmap. 
If the target rectangle is a different size than the source rectangle, this 
function will stretch or compress the bitmap to fit the target. 
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[ColorForeground - input 

The color value (such as CLR_BLACK) for the foreground of the bit- 
map. This parameter is ignored if the bitmap is not a monochrome 
(two-color) bitmap or if you specify DBM_IMAGEATTRS in the fl para- 
meter. 

lColorBackground - input 

The color value (such as CLR_WHITE) for the background of the 
bitmap. This parameter is ignored if the bitmap is not a monochrome 
(two-color) bitmap or if you specify DBM_IMAGEATTRS in the fl para- 
meter. 

fl- input 

A combination of the following flags: 

DBM_HALFTONE Before drawing, combines the bitmap using a bit- 
wise OR operation with a pattern containing alternate ones and zeros. 
DBM_IMAGEATTRS Only applies to monochrome (two-color) bit- 
maps. Causes this function to retrieve the foreground and background 
colors for the bitmap from the presentation space. Ignores the /Color- 
Foreground and [ColorBackground arguments. 

DBM_INVERT Invert the bitmap’s pixels during drawing. 
DBM_NORMAL Draw the bitmap with no special effects and with- 
out changing its size. With only this flag, this function will overpaint 
the target with the bitmap. 

DBM_STRETCH Stretch or compress the bitmap to fit the target 
rectangle. Changes the interpretation of the pilTarg parameter; pass 
the address of a RECTL that contains the target rectangle’s coordi- 
nates. To stretch a bitmap, this function duplicates scan lines; to com- 
press, it eliminates scan lines. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x207f - PMERR_INV_HPS 0x2009 - PMERR_BITMAP_IN_ 
USE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 
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NOTES 


This function draws a bitmap or a portion of a bitmap to a presenta- 
tion space, typically a window. A program can obtain the bitmap han- 
dle with GpiLoadBitmap or GpiCreateBitmap. 


EXAMPLE 


This example assumes that there is a bitmap resource defined in the 
program’s .RC file with the symbolic ID: ID_BITMAP. 


static HPS hos; 
static HBITMAP hbm; 


case WM_CREATE: 
{ 
SIZEL sigzgel = {0,0}; 
HDC hac; 


/* create a micro presentation space */ 
hdc = WinOpenWindowDC ( hwnd ); 
hps = GpiCreatePS ( hab, hdc, &sizel 
, GPIT_MICRO | PU_PELS 
| GPIA_ASSOC ); 


/* load the bitmap from the resource file 
use the size specified in .BMP file */ 
hbm = GpiLoadBitmap ( hps, 0, ID_BITMAP, 0, 0O ); 
} 


return 0; 


case WM_PAINT: 
{ 
RECTL rel; 
BOOL fSuccess; 


WinBeginPaint ( hwnd, hps, NULL ); 


/* draw the entire bitmap, stretch to fill window */ 
fSuccess = WinQueryWindowRect ( hwnd, &rcl ); 
fSuccess = WinDrawBitmap ( hps 

, hbm 
, NULL 
, (PPOINTL) &rcl 


118 OS/2 WARP Presentation Manager API 


; e 
» 
, DBM_STRETCH ); 


fSuccess = WinEndPaint ( hps ); 
} 


return 0; 





@® WinDrawBorder 





Draws a rectangular border. 


SYNTAX 


BOOL WinDrawBorder (HPS hps, PRECTL prel, LONG [VertWidth, 
LONGI/AHorzWidth, LONG /[ColorBorder, 
LONG/Colorlnierior, ULONG /l) 


PARAMETERS 

hps - input 

The presentation space to which to draw the border. 

prel - input 

The coordinates of the border rectangle in pixels. 

WertWidth - input 

The width of the border sides in pixels. The actual width may be dif- 
ferent if you specify DB_STANDARD or DB_DLGBORDER in the flargu- 
ment. 

lHorzWidth - input 

The width of the top and bottom borders in pixels. The actual width 
may be different if you specify DB_STANDARD or DB_DLGBORDER in 
the flargument. 

[ColorBorder - input 

The color of the border, such as CLR_BLACK. The function ignores 
this argument if you specify DB_AREAATTRS in the flargument. 
[ColorInterior - input 

The color of the interior, such as CLR_WHITE. The function ignores 
this argument if you specify DB_AREAATTRS in the fl argument or if 
you do not specify DB_INTERIOR. 

fl-anput 

Any combination of the following flags excluding these, which are 
mutually exclusive: DB_AREAMIXMODE, DB_DESTINVERT, DB_PAT- 
COPY, DB_PATINVER. These flags control the mix mode that this 
function uses to draw the border and the interior. The mix mode gov- 
erns how the border and the interior interact with the pixels already 
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on the display. The default is DB_PATCOPY, which, unless you change 
the current presentation space pattern, has the effect of overpainting 
the border and the interior onto the display, overwriting what was 
there before. 


DB_AREAMIXMODE § This function queries the current forground 
mix mode from the presentation space’s area bundle (set by Gpi- 
SetMixMode) and maps it into a GpiBitBlt raster operation. This 
function then uses the raster operation to draw both the border and 
the interior. The interior is not drawn unless you specify DB_INTE- 
RIOR. 

DB_DESTINVERT This function uses the ROP_DSTINVERT GpiBit- 
Blt raster operation to draw both the border and the interior. This 
raster operation inverts the destination pixels. The interior is not 
drawn unless you specify DB_INTERIOR. 

DB_PATCOPY This function uses the ROP_PATCOPY GpiBitBlt 
raster operation to draw both the border and the interior. This 
raster operation draws the current pattern set into the presentation 
space with GpiSetPattern. The default pattern is solid. The interior 
is not drawn unless you specify DB_INTERIOR. 

DB_PATINVERT This function uses the ROP_PATINVERT GpiBitBlt 
raster operation to draw both the border and the interior. This 
raster operation exclusive-ORs the current pattern set into the pre- 
sentation space with GpiSetPattern with the destination pixels. The 
default pattern is solid. The interior is not drawn unless you specify 
DB_INTERIOR. 

DB_AREAATTRS This flag governs the colors this function uses to 
draw the border and the interior (the interior is not drawn unless 
you specify DB_INTERIOR). Depending on the flags above, this 
function uses the current pattern set into the presentation space to 
draw the border and interior. See the Notes section below. If you do 
not specify DB_AREAATTRS, this function uses the /ColorBorder and 
/ColorIntenor arguments: 


Element Color 
Border foreground 1ColorBorder 
Border background 1ColorInterior 
Interior foreground 1ColorInterior 
Interior background 1ColorBorder 


If you specify DB_AREAATTRS, this function ignores the color argu- 
ments and instead queries the current presentation space’s area at- 
tribute bundle for the colors. 
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Element Color 
Border foreground area foreground color 
Border background area background color 
Interior foreground area background color 
Interior background area foreground color 


You can set the area attribute bundle’s colors with GpiSetColor and 
GpiSetBackColor (or use GpiSetAttrs). 

DB_DLGBORDER If you specify this flag, a standard dialog border 
is drawn, ignoring the lHorzWidth and [VertWidth arguments. If you 
specify DB_PATCOPY (the default), the border is drawn in the cur- 
rent active title bar color. If you specify DB_PATINVERT, the border 
is drawn in the current inactive title bar color. The interior is drawn 
in the color specified by the /ColorIntenor argument, but only if you 
specify DB_INTERIOR. 

DB_INTERIOR _ Draw the interior of the rectangle. 

DB_STANDARD If you specify this flag, the function calculates the 
width of the sides by multiplying /HorzWidth by the SV_CXBORDER 
system variable and calculates the width of the top and bottom by 
multiplying [VertWidth by SV_CYBORDER. You can set these system 
variables with WinSetSysValue (pg 356). Note that these system val- 
ues are not the same as a standard window’s border width, which are 
SV_CXSIZEBORDER and SV_CYSIZEBORDER. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1019 - PMERR_INVALID_ FLAG 
0x2068 - PMERR_INV_DRAW_BORDER_OPTION 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinSetSysValue -356, WinQuerySysValue -342 


NOTES 


This function uses a pattern to draw the border and any interior. A pat- 
tern is a monochrome bitmap that has a foreground and a back- 
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ground, whose colors you can modify separately. For example, if you 
set a horizontal line pattern by calling GpiSetPattern (hps, PATSYM_ 
HORIZ), the foreground is the horizontal lines and the background is 
the area between the lines. Note that the default pattern is PATSYM_ 
SOLID, which effectively has no background. 





WinDrawPointer 





Draws a pointer or an icon. 


SYNTAX 

BOOL WinDrawPointer (HPS hps, LONG x, LONG y, HPOINTER 
hptr, ULONG/JI) 

PARAMETERS 

hps - input 

The presentation space to which to draw the pointer or icon. 

x - input 


The x-coordinate, in pixels, at which to draw the pointer’s lower left 

corner on the target presentation space. 

y- input 

The y-coordinate, in pixels, at which to draw the pointer’s lower-left 

corner on the target presentation space. 

hptr - input 

The handle of the pointer to draw. 

fl- input 

A combination of the following flags: 

DP_HALFTONED Draw every other pixel for black areas in the 
pointer. 

DP_INVERTED Toggle black and white pixels. 

DP_MINI Draw the mini icon contained in a pointer. 

DP_NORMAL Draw normally. This is the default if you pass zero for 
this argument. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1019 - PMERR_INVALID_FLAG 
Oxl01b - PMERR_ INVALID _HPTR 
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0x207f - PMERR_INV_HPS 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 


WinCreatePointer -232, WinLoadPointer -243, WinQueryPointer -248, 
WinQueryPointerInfo -249 


NOTES 


None. 





@ WinDrawText 





Draws a line of text to a window, clipped to a rectangle. 


SYNTAX 


LONG WinDrawtText (HPS hps, LONG /[Count, PCH pch, PRECTL 
prel, LONG/Colorkoreground, LONG 
lColorBackground, ULONG /l) 


PARAMETERS 

hps - input 

The presentation space to which to draw the text. 

[Count - input 

The number of characters to draw. If you pass -1, this function assumes 
that pch points to a null-terminated string and calculates its length. 
Note that this function always stops drawing characters when it en- 
counters a carriage return or line feed character. 

pch - input 

Pass the address of a character array. 

prel - input/output 

On input, pass the address of a RECTL structure that contains the 
world coordinates of a rectangle that this function uses to format the 
text, based on the flargument. This function only returns a rectangle 
here if you specify DT_QUERYTEXTEXTENT in the flargument. 
[ColorForeground - input 

The color to use to draw the foreground of the text. This function ig- 
nores this argument if you specify DT_TEXTATTRS in the flargument. 
[ColorBackground - input 
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The color to use to draw the background of the text. This function ig- 
nores this argument if you specify DT_TEXTATTRS in the flargument. 
fl- input 

Any combination of the flags below. Some flags are mutally exclusive 
and thus cannot be combined. 


DT_BOTTOM Draw the text at the bottom of the rectangle. Cannot 
be used with DT_ TOP or DT_VCENTER. 

DT_CENTER Center the text horizontally in the rectangle. Cannot 
be used with DT LEFT or DT_RIGHT. 

DT_ERASERECT Before drawing the text, fill the rectangle with the 
current system background color. 

DT_EXTERNALLEADING If you specify this flag, this function ex- 
pands the returned rectangle by the font’s external leading, which 
is a measure of space between lines of text. This flag is ignored un- 
less you specify DT_TOPand DT_QUERYTEXTEXTENT. 

DT_HALFTONE Draw the text in a halftone style, with alternate pix- 
els set off and on. 

DT_LEFT Draw the text left-justified. Mutually exclusive with DT_ 
RIGHT and DT_CENTER. 

DT MNEMONIC If the text contains a tilde “~” character, underline 
the character following. The tilde is not drawn. 

DT_QUERYEXTENT Return the coordinates of the string in the prel 
argument without drawing the text. 

DT_RIGHT Draw the text right-justified in the rectangle. Mutually 
exclusive with DT. LEFT and DT_CENTER. 

DT_STRIKEOUT Draw a line through all of the characters. 

DT_TEXTATTRS This flag governs the colors this function uses to 
draw the text. If you specify this flag, this function queries the cur- 
rent foreground and background colors from the presentation 
space (you can set these with GpiSetColor and GpiSetBackColor). 
Without this flag, this function uses the J/ColorForeground and 
[ColorBackground arguments. 

DT_TOP Draw the text at the top of the rectangle. Mutually exclu- 
sive with DT_ BOTTOM and DT_VCENTER. 

DT _UNDERSCORE Underline the characters. 

DT_VCENTER Center the text vertically in the rectangle. Mutually 
exclusive with DT. BOTTOM and DT_TOP. 

DT_WORDBREAK If you specify this flag, this function only draws 
complete words that fit within the rectangle and ignores white space 
following the last word. Using this flag and the returned count of 
characters, a program can set up a loop to word-wrap multiple lines 
of text as shown in the example in the notes section. 
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RETURNS 


0 - an error occurred. 

Otherwise, the return count depends on whether you specified if 
DT_WORDBREAK. If so, the return count is the number of characters 
actually displayed. If not, the return count is the total number of char- 
acters is the string regardless of how many were actually displayed. 
Possible returns from WinGetLastError: 


0x1019 - PMERR_ INVALID _ 0x207f - PMERR_INV_HPS 
FLAG 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


NOTES 


This function draws a single line of text. To draw multiple lines word- 
wrapped within the specified rectangle, you must code a loop as shown 
in the example. 

This function uses the current font set in the presentation space 
with GpiSetCharSet. 


EXAMPLE 


This example word-wraps a string of text within a rectangle. Note that 
for simplicity, it hard codes the font height. A program should call 
GpiQueryFontMetrics instead of hard coding the height. 


case WM_PAINT: 
{ 
int cchDrawn = 0; /* total chars drawn */ 


int lHeight = 16; /* character height */ 


char *psz; /* character string */ 
ink ech: /* chars on a line xy 
pets len; /* total string length */ 


RECT FOL = 4 10, 10, 150, L250 J; 


hps = WinBeginPaint ( hwnd, NULLHANDLE, NULL ); 
GpiErase ( hps ); 


// initialize variables 


pez = (char *)jmatioc ({ 255 )} 
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strcepy ( psz, “This is a test, this is only a test” 
“ of the emergency broadcast system” ); 


len = strlen ( psz ); 


// loop through and word-wrap lines 
while ( cchDrawn < len ) 
{ 
cch = WinDrawText ( hps, -1, psz, &rcl 
, CLR_BLACK, CLR_WHITE 
, DT_WORDBREAK ) ; 


if ( cch == O ) 


break; 
cchDrawn += cch; 


1£ ( cchDrawn < len ) 


{ 
rcl.yTop -= lHeight; 


DSzZ #= cch; 


free ( psz ); 


fSuccess = WinEndPaint ( hps ); 
} 


return 0; 





@ WinFillRect 





Fills the interior of a rectangle with a color. 


SYNTAX 
BOOL WinFillRect (HPS hps, PRECTL prcl, LONG /Color) 


PARAMETERS 
hps - input 
The presentation space containing the rectangle to fill. 
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prel - input 

Pass the address of a RECTL containing the coordinates in pixels of the 
rectangle to fill. 

[Color - input 

The color used to fill the rectangle. By default, this is a color index 
(such as CLR_RED), but is interpreted as an RGB value (OxFFOOQ00 is 
red) if you have set the presentation space in RGB mode with 
GpiCreateLogColorTable. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x207f - PMERR_INV_HPS 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 





@® WinlnvertRect 





Inverts the interior of a rectangle. 


SYNTAX 
BOOL WinInvertRect (HPS hps, PRECTL prc!) 


PARAMETERS 
hps - input 
The presentation space containing the rectangle to invert. 


prel - input 
Pass the address of a RECTL containing the coordinates (in pixels) of 
the rectangle to invert. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x207f - PMERR_INV_HPS 


OTHER INFO 
Include file: pmwin.h Define: INGCL_WINWINDOWMGR 


Window Drawing Functions 127 


NOTES 


This function “flips the bits” of all of the pixels in the rectangle. Note 
that you can reverse the effect by calling the function again. 





WinMakePoints 





Initializes a point variable. 


SYNTAX 
BOOL WinMakePoints (HAB hab, PWPOINT pwpit, ULONG count) 


PARAMETERS 

hab - input 

Anchor block handle. 

pwpt - input/output 

Pass the address of an array of WPOINT structures. This function con- 
verts the array to POINYTL structures. 

count - input 

The number of elements in the array. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINRECTANGLES 


NOTES 
This function is a no-op in 32-bit OS/2. 





WinRealizePalette 





Loads a logical palette into the physical palette. 


SYNTAX 


LONG WinRealizePalette (HWND hwnd, HPS hps, PULONG 
pcChanged) 
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PARAMETERS 

hwnd - input 

The handle of the window that is realizing the palette. 

hps - input 

The handle of the presentation space containing the palette. You must 
create the palette with GpiCreatePalette and select it into the presen- 
tation space with GpiSelectPalette. 
pcChanged - output 

Pass the address of ULONG to which this function writes the count of 
physical colors changed. If entries are changed, this function writes 
the count to this ULONG and broadcasts WM_REALIZEPALETTE to all 
other windows. 


RETURNS 


The count of colors remapped in the physical palette, or PAL_LERROR 
if an error occurred. If the count is zero, no colors were remapped and 
the window does not need to repaint. 

Possible returns from WinGetLastError: 


0x207f - PMERR_INV_HPS 
0x2110 - PMERR_ NO_PALETTE_SELECTED 
Ox2111 - PMERR_INV_HPAL 


OTHER INFO 
Include file: pmwin.h Define: INCL_WIN 


NOTES 


A logical palette is a table of RGB colors that a program can create and 
select into a presentation space. For example, a program that displays 
a scanned image can create a logical palette that contains the same col- 
ors as the original image. The program can call this function to load 
the palette into the physical palette and repaint the image, matching 
the scanned picture as closely as possible. 

This function does not simply copy the logical palette into the 
physical palette. Instead, PM treats this function as a request and will 
copy zero or more of the logical palette entries. If more than one win- 
dow attempts to realize a palette, PM gives priority to the window with 
the focus. So, if a nonfocus window issues WinRealizePalette, PM will 
only modify the physical palette entries that the focus window isn’t us- 
ing. To ensure that the focus window has priority, all palette-aware win- 
dows should issue this function in response to the WM_REAL- 
IZEPALETTE message. 
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Unless you create the logical palette with the LCOL_OVER- 
RIDE_DEFAULT_COLORS option, PM reserves some physical palette 
entries to guarantee that nonpalette-aware windows can still display 
readable text. 





WinScrollWindow 





Scrolls the contents of a window. 


SYNTAX 


LONG WinScrollWindow (HWND hwnd, LONG LX, LONG LY, 
PRECTL prcl, PRECTL prelClip, HRGN 
hrgn, PRECTL prclUpdate, ULONG /1) 


PARAMETERS 

hwnd - input 

The window to scroll. 

IX - input 

The number of pixels to scroll horizontally. Use a negative value to 
scroll left, positive to scroll right. 

lY - input 

The number of pixels to scroll vertically. Use a negative value to scroll 
down, positive to scroll up. 

prel - input 

Pass the address of a RECTL containing the coordinates of the rectan- 
gle to scroll. Pass NULL to scroll the entire window. 

prelChp - input 

Pass the address of a RECTL containing the coordinates of a clipping 
rectangle. This function scrolls the intersection of this rectangle and 
the prel scroll rectangle. Pass NULL for no clipping. 

hrgn - output 

Pass the handle of a region created with GpiCreateRegion. This func- 
tion returns the set of rectangles uncovered by the scroll. Pass NULL- 
HANDLE if you don't need the region. 

prclUpdate - output 

Pass the address of a RECTL. This function returns the bounding rec- 
tangle of the update region in this rectangle. Pass NULL if you don’t 
need the rectangle. 

fl- input 

Any combination of these flags: 
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SW_INVALIDATEREGION _ If you specify this flag, this function in- 
validates the region uncovered by the scroll, thus generating the 
WM_PAINT message. 

SW_SCROLLCHILDREN If you specify this flag, this function 
changes the position of child windows by the amount of the scroll 
(LX and lY). Note that this function does not invalid the child win- 
dows to force them to repaint. 


RETURNS 

One of the the following: 

0 -RGN_ ERROR 1-RGN_ NULL 

2-RGN_ RECT 3 - RGN_COMPLEX 

Possible returns from WinGetLastError: 

0x1001 - PMERR INVALID _ 0x1019 - PMERR INVALID _ 
HWND FLAG 

OTHER INFO 


Include file: pmwin.h Define: INCL_WINWINDOWMGR 


NOTES 


If the window does not have the clip-children style, then this function 
will scroll the image of any child windows intersecting the scroll rec- 


tangle (prel). 





@ WinShowTrackRect 





Hides or shows a rectangle that the user can move or size. 


SYNTAX 
BOOL WinShowTrackRect (HWND hwnd, BOOL /Show) 


PARAMETERS 
hwnd - input 
The window that created the track rectangle with WinTrackRect. 
fShow - input 
Pass TRUE to show the tracking rectangle, FALSE to hide it. 
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RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINTRACKRECT 


SEE ALSO 
WinTrackRect -131 


NOTES 


You only need to hide and show the tracking rectangle if you issue 
WinTrackRect from a background thread. 





WinTrackRect 





Draws a rectangle that the user can move or size. 


SYNTAX 
BOOL WinTrackRect (HWND hwnd, HPS hps, PTRACKINFO piz) 


PARAMETERS 

hwnd - input 

The window to track over. You can pass HWND_DESKTOP to track over 
the entire screen. 

hps - input 

The presentation space that this function uses to apply a clip. You can 
pass NULLHANDLE if you don’t want clipping or if you want this func- 
tion to retrieve a presentation space handle from the hwnd argument. 
pti - input/output 

Pass the address of a TRACKINFO structure that describes the tracking 
operation. The user can use the mouse or the keyboard to move and 
size the tracking rectangle. Upon return, this function will return the 
size of the tracking rectangle in the rclTrack field of this structure. 


typedef struct _TRACKINFO /* ti */ 
{ 

LONG cxBorder; 

LONG cyBorder; 
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LONG cxGrid; 
LONG cyGrid; 
LONG cxKeyboard; 
LONG cyKeyboard; 
RECTL xelTrack; 
RECTL xrclBoundary; 
POINTL ptlMinTrackSize; 
POINTL ptlMaxTrackSize; 
ULONG fs; 

} TRACKINFO; 


cxBorder ‘The width of the left and right sides of tracking rectangle 
border in pixels. 
cyBorder ‘The width of the top and bottom sides of the tracking rec- 
tangle border in pixels. 
cxGrid The granularity of movement allowed horizontally. If you set 
this to one, the user can move or size the rectangle on each pixel. 
This field is ignored unless you specify TF_GRID in the fs field. 
cyGrid The granularity of movement allowed vertically. If you set this 
to one, the user can move or size the rectangle on each pixel. This 
field is ignored unless you specify 7/_GRID in the fs field. 
cxKeyboard ‘The number of pixels for each left or right arrow key. 
cyKeyboard ‘The number of pixels for each up or down arrow key. 
rclTrack ‘This function returns the final tracking rectangle size here. 
rclBoundary ‘The rectangle that constrains the tracking rectangle. 
The user will not be able to move or size the tracking rectangle out- 
side of this rectangle. By default, WinTrackRect ensures that at least 
a portion of the tracking rectangle stays inside this boundary; if you 
want the entire tracking rectangle to stay inside, specify 
TF_ALLINBOUNDARY in the fs field. 
ptlMinTrackSize The minimum horizontal and vertical size of the 
tracking rectangle. The user will not be able to size the rectangle 
smaller than the x and y fields in this point. 
ptlMaxTrackSize The maximum horizontal and vertical size of the 
tracking rectangle. The user will not be able to size the rectangle 
larger than the x and y fields in this point. 
fs ‘Tracking flags. Any combination of the following: 
TF_ALLINBOUNDARY Keep the entire tracking rectangle within 
the boundary rectangle. 
TF_BOTTOM Let the user move the bottom side of the tracking 
rectangle. 
TF_GRID_ Snap the tracking rectangle to multiples of the cxGnd 
and cyGmd fields. 
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TF_LEFT Let the user move the left side of the tracking rectangle. 

TF_MOVE Let the user move the entire tracking rectangle: user 
cannot size the rectangle with this flag. This flag is equivalent to 
TF_LEFT | TF_RIGHT | TF_TOP | TF_BOTTOM. 

TF_RIGHT Let the user move the right side of the tracking rec- 
tangle. 

TF_SETPOINTERPOS _ If you specify this flag, this function repo- 
sitions the mouse pointer to center it, based on any other tracking 
flags. For example, if you specify 7F_BOTTOM and TF_SET- 
POINTERPOS, the mouse pointer will be centered at the bottom 
of the tracking rectangle. 

TF_TOP Let the user move the top side of the tracking rectangle. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID_ 0x207f - PMERR_INV_HPS 
HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINTRACKRECT 


SEE ALSO 
WinShow IrackRect -130 


NOTES 


This function draws a rectangle in the exclusive-or mix mode that the 
user Can move or size based on the tracking flags. This rectangle is sim- 
ilar to the rectangle drawn by a frame window when the user drags the 
size border. 

This function enters a modal message loop and doesn’t return un- 
til the user ends or aborts the tracking operation. The user can end the 
tracking by pressing the Return key or releasing the mouse; to abort, 
the user can press the Escape key. If the user aborts, this function re- 
turns a FALSE value, but updates the rclTrack field to the last size and 
position of the tracking rectangle. 

If you specify 7F_GRID, and the user presses an arrow key, this 
function moves or sizes the rectangle using the largest multiple of 
cxGrid or cyGrd that is smaller than cxKeyboard or cyKeyboard. If you pass 
cxGrid > cxKeyboard or cyGrid > cyKeyboard, this function ignores key- 
board input for moving and sizing. 
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EXAMPLE 


This example displays a tracking rectangle that the user can move, but 
not size. It constrains the tracking rectangle to stay within the bounds 
of the window. It only allows the tracking rectnagle to move on 10-pixel 
boundaries, either with the mouse or the keyboard. 


TRACKINFO 
RECTL 


roils 


cis /* track-info struct */ 


/* window rectangle */ 


/* limit track rectangle to window */ 


WinQueryWindowRect ( hwnd, &rcl ); 


/* set up a move track rectangle on a 10-pixel grid */ 
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ts = TF_MOVE | TF_GRID; 


/* display tracking rectangle */ 


fSuccess 


= WinTrackRect 


( hwnd, NULLHANDLE, &ti ); 
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aT display window is different from other output devices 
such as a printer, because the user can overlap windows. Thus, 
window procedures must refresh, or repaint, their windows on de- 
mand. For example, if the user closes a window that overlays another, 
the window underneath must redraw its display. PM passes the under- 
lying window a WM_PAINT message to signal this event. All PM window 
procedures must process this message to draw to their associated win- 
dows. 

Since all PM programs share the same display (desktop), it’s im- 
portant that one window doesn’t overwrite the display of another. To 
prevent that from happening, PM clips any window procedure’s out- 
put to its window rectangle. In addition, it’s ttme-consuming to write to 
a display, especially at high resolutions and color depths; therefore, 
PM again applies clipping to a window’s output to minimize the actual 
number of pixels drawn. 

All of PM’s clipping is on the basis of a data type called a region, 
which is a collection of rectangles (all windows are rectangles). To pre- 
vent one window from overwriting others, PM maintains a visible re- 
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gion for each window, and clips the window procedure’s output to this 
region. To optimize painting, PM maintains the invalid or update re- 
gion, and also clips output to this region. PM provides functions so that 
programs can manipulate these regions, and these are the functions 
covered in this chapter. 


The Invalid Region and the WM_PAINT Message 


Whenever the user moves, sizes, or closes a window, the action may un- 
cover other windows or portions of them. We say that the uncovered 
windows are invalid, and need to repaint. All window procedures must 
process the WM_PAINT message to respond to this event. Typically, the 
window procedure will call WinBeginPaint (pg 105) near the start of 
the WM_PAINT processing. WinBeginPaint performs the following 
tasks: 


1. It applies a clip to the presentation space for the invalid region; PM 
will restrict any subsequent output to the invalid region. In other 
words, PM will discard any output that falls outside of the invalid re- 
gion. 

2. PM validates, or removes, the invalid region, thus preventing the 
window procedure from receiving any more WM_PAINT messages 
until the window is again invalid. 

3. It optionally returns a cached-micro presentation space handle. 


Programs can force a window to repaint by calling WinInvalidate- 
Rect (pg 138) to create a non-NULL invalid region for the window, 
which causes PM to pass the window procedure a WM_PAINT message. 
Note that it’s usually ineffective to explicitly send or post the window a 
WM_PAINT message. Since there’s probably no invalid region, Win- 
BeginPaint will clip the presentation space completely. 


Clipping and Invalid Region Functions 


WinExcludeUpdateRegion clips a presentation space to a window’s in- 
valid region (pg 137). 

WinInvalidateRect adds a rectangle to a window’s invalid region (pg 
138). 
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WinInvalidateRegion adds a set of rectangles to a window’s invalid re- 
gion (pg 139). 

WinLockVisRegions prevents output to all visible regions on the desk- 
top (Appendix A). 

WinLockWindowUpdate prevents output to a window and its children 
(pg 142). 

WinQueryUpdateRect retrieves a bounding rectangle for a window’s 
invalid region (pg 142). 

WinQueryUpdateRegion retrieves the set of rectangles that comprise a 
window’s invalid region (pg 143). 

WinQueryVisibleRegion retrieves the set of rectangles that comprise a 
window's visible region (pg 144). 

WinSetVisibleRegionNotify tells PM to notify a window when its visible 
region changes (pg 145). 

WinUpdateWindow sends a WM_PAINT message immediately (pg 146). 
WinValidateRect removes a rectangle from a window's invalid region 
(pg 147). 

WinValidateRegion removes a set of rectangles from a window’s invalid 
region (pg 148). 





WinExcludeUpdateRegion 


Clips a presentation space to a window’s invalid region. 


SYNTAX 
LONG WinExcludeUpdateRegion (HPS hps, HWND hwnd) 


PARAMETERS 

hps - input 

The presentation space to which to apply the clip. 
hwnd - input 

The window containing the invalid region. 


RETURNS 
One of the the following: 


0 - RGN_ERROR 1 - RGN_NULL 
2 - RGN_RECT 3 - RGN_COMPLEX 
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Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinBeginPaint -105, WinGetPS -108, WinValidateRegion -139 


NOTES 


A window procedure receives a WM_PAINT message when all or part of 
the window needs to be repainted. The portion of the window to re- 
paint is called the invalid or update region. Normally, a window proce- 
dure issues WinBeginPaint, which applies clipping to the window’s 
presentation space so that any output is restricted to the invalid region; 
in other words, if the program issues functions that write text or graph- 
ics outside of the invalid region, the device driver discards that output. 

A program can use this function along with WinValidateRegion as 
an alternative to WinBeginPaint, which always validates the entire in- 
valid region. With this technique, a program can repaint only a part 
of the window each paint message, to ensure that the paint message 
doesn’t take too long. Note that a program can use a background 
thread as an alternate technique to avoid locking the messaging system 
during lengthy repaints. 





@ WinlnvalidateRect 





Adds a rectangle to a window’s invalid region. 


SYNTAX 

BOOL WinInvalidateRect (HWND hwnd, PRECTL prcl, BOOL 
flnvChildren) 

PARAMETERS 

hwnd - input 

The window that this function should invalidate. 

prel - input 


The coordinates (in pixels) of the rectangle to invalidate. Pass NULL 
to invalidate the entire window. 
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flnovChildren - input 

Pass TRUE if you want to invalidate any child windows intersected by 
prel, FALSE if not. If the parent window does not have the CS_CLIP- 
CHILDREN style, you should pass TRUE, since without that style, the 
parent can paint over its children, and the children should be invali- 
dated to ensure they can repaint. If the parent has the clip-children 
style, then you can safely minimize the number of WM_PAINT mes- 
sages generated by passing FALSE. This parameter is ignored if the 
window specified by hwnd has no descendants. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_ 0x1019 - PMERR_INVALID_ 
HWND FLAG 
OTHER INFO 


Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinBeginPaint -105, WinInvalidateRegion -139, 
WinUpdate Window -146 


NOTES 


A program can issue this function to force a window to receive a 
WM_PAINT message. If the window has the CS_SYNCPAINT style, this 
function sends the message immediately; otherwise, it effectively 
places the message in the window's message queue. Ifa program needs 
to force an immediate message on windows without the synchronous- 
paint style, issue this function followed by WinUpdateWindow. 





WinlnvalidateRegion 


Adds a set of rectangles to a window’s invalid region. 


SYNTAX 


BOOL WinInvalidateRegion (HWND hwnd, HRGN hrgn, BOOL 
filnvChildren) 
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PARAMETERS 

hwnd - input 

The window that this function should invalidate. 

hrgn - input 

The handle of the region that contains the set of rectangles to add. 
Pass NULL to invalidate the entire window. 

finoChildren - input 

Pass TRUE if you want to invalidate any child windows intersected by 
the region, FALSE if not. If the parent window does not have the 
CS_CLIPCHILDREN style, you should pass TRUE, since without that 
style, the parent can paint over its children, and the children should 
be invalidated to ensure they can repaint. If the parent has the clip- 
children style, then you can safely minimize the number of WM_PAINT 
messages generated by passing FALSE. This parameter is ignored if the 
window specified by hwnd has no descendants. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_ 0x1019 - PMERR_ INVALID _ 
HWND FLAG 
OTHER INFO 


Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinBeginPaint -105, WinInvalidateRect -138, WinUpdate Window -146 


NOTES 


A program can issue this function to force a window to receive a WM_ 
PAINT message. If the window has the CS_SYNCPAINT style, this func- 
tion sends the message immediately; otherwise, it effectively places the 
message in the window's message queue. If a program needs to force 
an immediate message on windows without the synchronous-paint 
style, issue this function followed by WinUpdateWindow. 

Before issuing this function, you must first create the region with 
GpiCreateRegion. 
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@ WinLockVisRegions 


Prevents output to all visible regions on the desktop. 


SYNTAX 
BOOL WinLockVisRegions (HWND hwndDeskiop, BOOL fLock) 


PARAMETERS 


hwndDesktop - input 

The desktop window handle. 

fLock - input 

Pass TRUE to lock, FALSE to unlock. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinLockWindowUpdate -141 


NOTES 


This function prevents output to all windows on the desktop. PM main- 
tains a lock count—if the same thread locks the desktop more than 
once, it must unlock an equal number of times before the lock is re- 
leased. 

While the desktop is locked, you should not send any messages 
nor call any functions that send messages. 





@ WinLockWindowUpdate 


Prevents output to a window and its children. 


142 OS/2 WARP Presentation Manager API 


SYNTAX 
BOOL WinLockWindowUpdate (HWND hwndDesktop, HWND hwnd) 


PARAMETERS 


hwndDeshtop - input 

The desktop window handle. 

hwnd - input 

The window to lock. Pass NULLHANDLE to unlock. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinLockVisRegions -Appendix A, WinSetVisibleRegionNotify -145 


NOTES 


This function prevents output by the specified window and any of its 
descendants. If the window procedures run on multiple threads, the 
threads continue to run while the lock is in place; however, PM ignores 
all output while the window(s) is locked. 

If a window has issued WinSetVisibleRegionNotify, this function 
sends the WM_VNRENABLED and WM_VNRDISABLED messages to 
that window. 





@ WinQueryUpdateRect 


Retrieves a bounding rectangle for a window's invalid region. 


SYNTAX 
BOOL WinQueryUpdateRect (HWND hwnd, PRECTL prc!) 


PARAMETERS 
hwnd - input 
The window for which the upate rectangle should be retrieved. 
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prel- output 
Pass the address of a RECTL structure where this function returns the 
coordinates in pixels of the update rectangle. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinQueryUpdateRegion -143, WinInvalidateRect -138, 
WinInvalidateRegion -139, WinBeginPaint -105, WinValidateRect -147, 
WinValidateRegion -148, WinExcludeUpdateRegion -137 


NOTES 


This function retrieves the coordinates of the smallest rectangle that 
bounds a window’s update region. Note that this same rectangle is re- 
turned by WinBeginPaint. A program could use this function along 
with WinValidateRect and WinExcludeUpdateRegion instead of Win- 
BeginPaint. 





WinQueryUpdateRegion 


Retrieves the set of rectangles that comprise a window’s invalid region. 


SYNTAX 
LONG WinQueryUpdateRegion (HWND hwnd, HRGN hrgn) 


PARAMETERS 

hwnd - input 

The window for which the update region should be retrieved. 

hrgn - input/output 

Pass the handle of an empty region. This function returns the set of 
rectangles that comprise the window’s update region in this argument. 
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RETURNS 

One of the the following: 

0 - RGN_ERROR © 1 - RGN_NULL 

2 - RGN_RECT 3 - RGN_COMPLEX 


Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinQueryUpdateRect -142, WinInvalidateRect -138, 
WinInvalidateRegion -139, WinBeginPaint -105, WinValidateRect -147, 
WinValidateRegion -148, WinExcludeUpdateRegion -137 


NOTES 


This function retrieves the set of rectangles that comprise the window's 
invalid region. A program could use this function along with Win- 
ValidateRegion and WinExcludeUpdateRegion instead of WinBegin- 
Paint. 

Before issuing this function, you must create the region with Gpi- 
CreateRegion. 





@ WinQueryVisibleRegion 
Retrieves the set of rectangles that comprise a window's visible region. 


SYNTAX 
ULONG WinQueryVisibleRegion (HWND hwnd, HRGN hrgn) 


PARAMETERS 

hwnd - input 

The window for which the visible region should be retrieved. 

hrgn - input/output 

Pass the handle of an empty region. This function returns the set of 
rectangles that comprise the window’s visible region in this argument. 
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RETURNS 

One of the the following: 

0-RGN_ ERROR 1-RGN_NULL 

2 -RGN_ RECT 3- RGN COMPLEX 


Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinQueryUpdateRegion -143, WinIsWindowVisible -281 


NOTES 


Before issuing this function, you must first create the region with 
GpiCreateRegion. 





WinSetVisibleRegionNotify 


Tells PM to notify a window when its visible region changes. 


SYNTAX 
BOOL WinSetVisibleRegionNotify (HWND hwnd, BOOL f) 


PARAMETERS 

hwnd - input 

The window to notify when its visible region changes. 

f- input 

Pass TRUE to start receiving notification, FALSE to stop. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 
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SEE ALSO 
WinQueryVisibleRegion -144, WinLockWindowUpdate -142 


NOTES 


After you issue this function passing TRUE, PM will send your window 
the WM_VNRDISABLED message when your window procedure should 
not write to its window, and WM_VNRENABLED when it’s okay to write 
to the window. The first message parameter of WM_VNRENABLED will 
be TRUE if the visible region has changed, FALSE if it hasn’t. 

After issuing this function, the window procedure will also receive 
the same messages when WinLockWindowUpdate is called on your 
window. 

In either case, your program can call WinQueryVisibleRegion to 
retrieve the new visible region. 





@ WinUpdateWindow 


Sends a WM_PAINT message immediately. 


SYNTAX 
BOOL WinUpdateWindow (HWND hwnd) 


PARAMETERS 
hwnd - input 
The window to which to send the WM_PAINT message. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_ INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinInvalidateRect -138, WinInvalidateRegion -139 
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NOTES 


This function examines the update region of the window and immedi- 
ately sends a WM_PAINT message if the window is invalid. If the win- 
dow has descendants, this function does the same for the descendant 
windows. If the window has no invalid region, this function is ineffec- 
tive. 

Note that this function is unnecessary for windows with the syn- 
chronous-paint style; PM sends such windows WM_PAINT immediately 
whenever they become invalid. 





WinValidateRect 





Removes a rectangle from a window’s invalid region. 


SYNTAX 


BOOL WinValidateRect (HWND hwnd, PRECTL prcl, BOOL 
Children) 


PARAMETERS 

hwnd - input 

The window to validate. 

prel - input 

The coordinates of the rectangle (in pixels) to remove from the in- 
valid region. 

{Children - input 

Pass ‘TRUE to remove the rectangle from any descendant windows, 
FALSE otherwise. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinValidateRegion -148, WinInvalidateRect -138, 
WinInvalidateRegion -139, WinBeginPaint -105 
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NOTES 


A window procedure receives a WM_PAINT message when all or part of 
the window needs to be repainted. The portion of the window to re- 
paint is called the invalid or update region. Normally, a window proce- 
dure issues WinBeginPaint, which validates the entire invalid region to 
prevent another WM_PAINT message until the window is again invalid. 

A program can use this function as an alternative to WinBegin- 
Paint. With this technique, a program can repaint only a part of the 
window each paint message, to ensure that each paint message doesn’t 
take too long. Note that a program can use a background thread as an 
alternate technique to avoid locking the messaging system during 
lengthy repaints. 

This function removes a rectangle from a window’s invalid region. 
By doing so, the caller indicates that it has repainted the rectangle so 
it is no longer invalid. If there are rectangles remaining in the invalid 
region, the window procedure will receive a subsquent WM_PAINT 
message after returning. 





WinValidateRegion 


Removes a set of rectangles from a window’s invalid region. 


SYNTAX 


BOOL WinValidateRegion (HWND hwnd, HRGN hrgn, BOOL 
fChildren) 


PARAMETERS 

hwnd - input 

The window to validate. 

hrgn - input 

The handle for the region that contains the set of rectangles to remove 
from the window’s invalid region. 

fChildren - input 

Pass TRUE to remove the rectangle from any descendant windows, 
FALSE otherwise. 
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RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinValidateRect -147, WinInvalidateRect -138, 
WinInvalidateRegion -139, WinBeginPaint -105 


NOTES 


A window procedure receives a WM_PAINT message when all or part of 
the window needs to be repainted. The portion of the window to re- 
paint is called the invalid or update region. Normally, a window proce- 
dure issues WinBeginPaint, which validates the entire invalid region to 
prevent another WM_PAINT message until the window is again invalid. 

A program can use this function as an alternative to WinBegin- 
Paint. With this technique, a program can repaint only a part of the 
window each paint message, to ensure that each paint message doesn’t 
take too long. Note that a program could use a background thread as 
an alternate technique to avoid locking the messaging system during 
lengthy repaints. 

This function removes a set of rectangles from a window’'s invalid 
region. By doing so, the caller indicates that it has repainted the rec- 
tangles so they are no longer invalid. If there are rectangles remaining 
in the invalid region, the window procedure will receive a subsquent 
WM_PAINT message after returning. 

Before issuing this function, the program must create the region 
with GpiCreateRegion. 
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PM program uses menus to display a visible list of commands that 

the program supports. Menus are windows of the class WC_MENU. 
See WinRegisterClass (pg 28) for more information on window classes. 
When the user selects a command from the menu, the menu window 
notifies its owner, passing the WM_COMMAND, WM_SYSCOMMAND , 
WM_HELP, or WM_INITMENU message, depending on the menu 
item’s style as described below. A typical PM standard window (see 
WinCreateStdWindow (pg 17)) will have at least two menus: an action 
bar menu and a system menu. In addition, PM supports floating or pop- 
up menus that are not directly attached to the standard window. 

The menu window contains menu items, which can be text, 
bitmap, or customized, known as ownerdraw. It’s important to note 
that the menu items are not separate windows; they are just text or 
bitmaps drawn by the menu window or by the menu window owner in 
the case of ownerdraw. Each menu item has an ID that is reported to 
the owner in the WM_COMMAND or WM_INITMENU messages. 

Any menu item can be connected to another menu window, called 
a submenu. When the user selects a submenu item, the submenu is 
made visible. Each submenu is a separate window, populated with 
menu items. Menu items that do not connect to a submenu are some- 
times called command items, since the menu generates WM_COMMAND 
when the user selects them. 
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If an item on a submenu connects to another submenu, the con- 
nected submenu is called a cascaded menu. PM supports two kinds of 
cascades: normal and conditional. ‘The menu item that connects to a 
conditional cascade draws a button-like object that the user must select 
to display the cascade, unlike normal cascades, which display automat- 
ically when the user selects the menu item. In addition, conditonal 
cascades always have a default item (designated with a check mark). 


Creating a Menu 


The easiest way to create an action bar menu on a standard window 
(see WinCreateStdWindow (pg 17)) is to define the menu as a re- 
source in a resource file and specify #CF_MENU in the WinCreate- 
StdWindow call. (See the IBM OS/2 Toolkit Tools Reference for help 
on defining a menu resource. ) 

If, for some reason, you need to create a menu without calling 
WinCreateStdWindow, you can either load the menu from a resource 
(WinLoadMenu (pg 160) or create the menu entirely in memory 
(WinCreateMenu (pg 154)). 


Menu Window Styles 


Like all windows, menus support the normal window styles such as 
WS_VISIBLE. (See WinCreateWindow (pg 22) for more information 
on normal window styles.) In addition, menus define window styles 
that apply only to menus. Note: do not confuse menu window styles 
with menu item styles. Menu items are not separate windows as de- 
scribed above. 


MS_ACTIONBAR The menu window draws its items side by side 
rather than vertically. 

MS_TITLEBUTTON The menu window uses CUA colors when 
drawing its menu items. 

MS_VERTICALFLIP The menu positions submenus above the 
menu window rather than below. Menus automatically adopt this 
style when the submenu would otherwise be clipped by the bottom 
of the desktop window. 

MS _CONDITIONALCASCADE ‘The menu item that connects to a 
submenu with this style draws a button-like object that the user must 
select to display the conditional cascaded submenu. A submenu with 
this style maintains a default item, designated with a check mark. 
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Menu Item Styles 


Menu item styles apply to the items that populate menu windows. Do 
not confuse them with the menu window styles described above, which 
apply to the windows that contain menu items. 


MIS TEXT ‘The menu item consists of text. This style cannot be 
combined with MIS_BITMAP or MIS_OWNERDRAW. 

MIS BITMAP ‘The menu item consists of a bitmap. This style cannot 
be combined with M/JS_TEXT or MIS_OWNERDRAW. 

MIS OWNERDRAW The menu window does not draw the menu 
item. Instead, it passes WM_MEASUREITEM and WM_DRAWITEM 
messages to the owner window, which must draw the menu item. 
This style cannot be combined with M/S_TEXT or MIS_BITMAP. 

MIS SUBMENU The menu item is connected to another menu win- 
dow. If the connected submenu does not have the MS_-CONDITION- 
ALCASCADE style, when the user selects this item, the menu displays 
the submenu and generates a WM_INITMENU message to its owner, 
passing the menu item ID. If the user selects a menu item connected 
to asubmenu with the MS_CONDITIONALCASCADE style, the menu 
window queries the submenu’s default item ID and generates a 
WM_COMMAND message. 

MIS _SYSCOMMAND The menu item generates the WM_SYSCOM- 
MAND message rather than the WM_COMMAND message. Note that 
if the menu is in a standard window, the client window procedure 
does not receive WM_SYSCOMMAND unless it subclasses its frame 
window. 

MIS HELP The menu generates the WM_HELP message rather 
than WM_COMMAND. 

MIS STATIC ‘The menu item cannot be selected; for display only. 

MIS BUTTONSEPARATOR The menu window draws a box around 
menu items with this style. In addition, if the menu item is on a 
menu window with the MS_ACTIONBAR window style, the menu 
window draws the item right-justified. Also, the user cannot select 
the item with the arrow keys. 

MIS BREAK ‘The menu window starts a new column for a menu 
item with this style. 

MIS BREAKSEPARATOR The menu window starts a new column 
for menu items with this style. In addition, the menu window draws 
a line between the new column and the previous column. 


Menus 153 


Menu Item Attributes 


In addition to the menu item styles shown above, menu items also have 
attributes. The basic difference between menu item styles and attrib- 
utes is that it’s simpler to change menu item attributes dynamically 
with the MM_SETITEMATTR message. Also, menu item attributes are 
Boolean values, TTRUE or FALSE. 


MIA CHECKED If this attribute is TRUE, the menu draws a check 
mark to the left of the item. 

MIA DISABLED If this attribute is TRUE, the menu draws the menu 
item in a gray color and the user cannot select the item. 

MIA NODISMISS | If this attribute is FALSE, the menu window dis- 
appears when the user selects the menu item. If this attribute is 
TRUE, the menu window does not dismiss until the user selects an- 
other item or presses the Escape key. 

MIA FRAMED If this attribute is TRUE, the menu draws a box 
around the item. Note: the menu adopts this attribute automati- 
cally; programs do not normally set it. 


Menu Functions 





WinCheckMenultem checks or unchecks a menu item (pg 153). 
WinCreateMenu creates a menu from a memory template (pg 154). 
WinEnableMenultem enables or disables a menu item (pg 157). 
WinIsMenultemChecked determines if a menu item is checked (pg 157). 
WinIsMenultemEnabled determines if a menu item is enabled (pg 158). 
WinIsMenultemValid determines if a menu item is valid (pg 159). 
WinLoadMenu loads a menu from a resource (pg 160). 
WinPop-upMenu displays and processes a floating pop-up menu 
(pg 161). 

WinSetMenultemText changes a menu item’s text (pg 164). 





@ WinCheckMenultem 





Checks or unchecks a menu item. 
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SYNTAX 

BOOL WinCheckMenultem (HWND hwndMenu, USHORT id, 
BOOL /) 

PARAMETERS 


hwndMenu - input 

The top-level menu window’s handle; for example, the action bar. 
id - input 

The menu item’s identifier. 

f- input 

Pass TRUE to check the menu item, FALSE to uncheck it. 
RETURNS 

TRUE if successful, FALSE otherwise. 

Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinIsMenultemChecked -157, WinSendMsg -54, 
WinWindowFromID -322 


NOTES 


This is actually a macro defined in PMWIN.H that issues WinSendMsg 
to send the MM_SETITEMATTR message to the menu window. 

A client window procedure can obtain the action bar’s window 
handle by issuing WinWindowFromID and passing the frame window's 


handle and FID_MENU. 





@® WinCreateMenu 





Creates a menu from a memory template. 


SYNTAX 
HWND WinCreateMenu (HWND hwnd, PVOID lpTemplate) 
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PARAMETERS 

hwnd - input 

The parent and owner of the top-level menu window. See Win- 
CreateWindow for more information on parent and owner windows. 
Typically this is a frame window for menus on standard windows, and 
HWND_DESKT OP for floating pop-up menus. 

lp Template 

Points to a memory template that you must initialize before calling this 
function. You can initialize the template yourself or call DosGet- 
Resource to read the template from a resource using the RT_MENU 
type. The menu template consists of a series of MT (menu template) 
and MTT (menu template item) structures. You define an MT structure 
for the entire menu, followed by an M77and MT for the first submenu 
(in that order). After the submenu’s MT, list one M77 structure for 
each menu item on the submenu. Define additional MTT7 and MT 
structures for each additional submenu, each pair immediately fol- 
lowed by MYT structures for the submenu’s menu items. 


typedef struct _mti 
{ 


USHORT afStyle; 
USHORT pad; 
USHORT iditem; 
CHAR en} 

} MTI; 


afStyle The menu item style (MIS_XX%X) bits for the menu item. 

pad Documented as reserved, but appears to have the menu item at- 
tributes (MIA_ XXX) bits for the menu item. 

iditem ‘The menu item identifier. 

ch[{1] For MIS_TEXT, the menu item text string. For M/S_BITMAP, a 
string of the form “#xxxx,” where xxxx is a bitmap resource identi- 
fier. For MIS_-OWNERDRAW, not used. 


typedef struct _mt 
{ 


ULONG len; 
USHORT codepage; 
USHORT reserved; 
USHORT CME. 
MTI rgMti (LJ; 


} MT; 
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len The length of the menu template in bytes. 

codepage The menu’s code page, for example 850. 

reserved Unused, but the resource compiler sets to the value 4. 

cMti The number of menu item template structures that immedi- 
ately follow. 

rgMti One or more menu item template structures. 


RETURNS 


The menu window handle, or NULLHANDLE if an error occurred. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMENUS 


SEE ALSO 


WinLoadMenu -160, WinPop-upMenu -161, WinCreateWindow -22, 
WinWindowFromID -322, WinSetWindowUShort -317 


NOTES 


This function creates a menu from a memory template that you can fill 
in manually or load from a resource with DosGetResource. If the menu 
is defined as a resource, it’s easier just to call WinLoadMenu instead of 
this function, but this function lets you modify the template in mem- 
ory before you create the menu. 

This function assigns the (JD_MENU identifier to the new menu. If 
your frame window already has an action bar menu, you should change 
the new menu’s identifier by calling WinSetWindowUShort with 
QWS_ID, specifying the new menu window handle and a new identifier. 

After creating the menu, you can display it as a floating pop-up 
menu with WinPopupMenu, or attach it as an action bar menu to a 
frame window. This function assigns the FJD_MENU identifier to the new 
menu window, therefore, to attach to a frame, just send the WM_UP- 
DATEFRAME message to the frame window after creating the menu. 

Another way to create a menu window is to fill in the menu tem- 
plate as described above, and then call WinCreateWindow, specifying 
WC_MENU as the window class and passing the menu template’s ad- 
dress as the “control data” parameter. This method is functionally 
equivalent to calling WinCreateMenu. 
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@ WinEnableMenultem 





Enables or disables a menu item. 


SYNTAX 

BOOL WinEnableMenultem (HWND hwndMenu, USHORT id, 
BOOL f) 

PARAMETERS 


hwndMenu - input 

The top-level menu window’s handle; for example, the action bar. 
id - input 

The menu item’s identifier. 

f- input 

Pass TRUE to enable the menu item, FALSE to disable it. 
RETURNS 

TRUE if successful, FALSE otherwise. 

Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinIsMenultemEnabled -158, WinSendMsg -54, 
WinWindowFromID -322 


NOTES 


This is actually a macro defined in PMWIN.H that issues WinSendMsg 
to send the MM_SETITEMATTR message to the menu window. 





@® WinlsMenultemChecked 





Determines if a menu item is checked. 
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SYNTAX 
BOOL WinIsMenultemChecked (HWND hwndMenu, USHORT id) 


PARAMETERS 


hwndMenu - input 

The top-level menu window’s handle; for example, the action bar. 
id - input 

The menu item’s identifier. 


RETURNS 


TRUE if item is checked, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinCheckMenultem -153, WinSendMsg -54, 
WinWindowFromID -322 


NOTES 


This is actually a macro defined in PMWIN.H that issues WinSendMsg 
to send the MM_QUERYITEMATTR message to the menu window. 





@ WinlsMenultemEnabled 





Determines if a menu item is enabled. 


SYNTAX 
BOOL WinIsMenultemEnabled (HWND hwndMenu, USHORT id) 


PARAMETERS 

hwndMenu - input 

The top-level menu window’s handle; for example, the action bar. 
id - input 

The menu item’s identifier. 
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RETURNS 


TRUE if item is enabled, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinEnableMenultem -157, WinSendMsg -54, 
WinWindowFromID -322 


NOTES 


This is actually a macro defined in PMWIN.H that issues WinSendMsg 
to send the MM_QUERYITEMATTR message to the menu window. 





WinlsMenultem Valid 





Determines if a menu item is valid. 


SYNTAX 
BOOL WinIsMenultemValid (HWND hwndMenu, USHORT 7d) 


PARAMETERS 

hwndMenu - input 

The top-level menu window’s handle; for example, the action bar. 
id - input 

The menu item’s identifier. 


RETURNS 


TRUE if zd is a valid menu item, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 
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SEE ALSO 
WinSendMsg -54, WinWindowFromID -322 


NOTES 


This is actually a macro defined in PMWIN.HA that issues WinSendMsg 
to send the MM_ISITEMVALID message to the menu window. 





@ WinLoadMenu 





Loads a menu from a resource. 


SYNTAX 

HWND WinLoadMenu (HWND hwnd, HMODULE hmod, 
USHORT 7d) 

PARAMETERS 

hwnd - input 


The window that will act as the menu’s owner and parent. See Win- 
CreateWindow for more information on parent and owner windows. 
Typically, this is a frame window for menus on standard windows, and 
HWND_DESKTOP for floating pop-up menus. 

hmod - input 

The module handle of the DLL that contains the menu resource, or 
pass NULLHANDLE if the menu resource is bound to the current ex- 
ecutable. 

id - input 

The resource identifier of the menu. 


RETURNS 


The menu window handle, or NULLHANDLE if an error occurred. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 
0x100a - PMERR_RESOURCE_NOT_FOUND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMENUS 
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SEE ALSO 


WinCreateMenu -154, WinPopupMenu -161, WinCreateWindow -22, 
WinWindowFromID -322, WinSetWindowUShort -317 


NOTES 


This function assigns the FJD_MENU identifier to the new menu. If your 
frame window already has an action bar menu, you should change the 
new menu’s identifier by calling WinSetWindowUShort with QWS_JD, 
specifying the new menu window handle and a new identifier. 

After creating the menu, you can display the menu as a floating 
pop-up menu with WinPopupMenu, or attach it as an action bar menu 
to a frame window. This function assigns the FJD_MENU identifier to 
the new menu window, therefore to attach to a frame, just send the 
WM_UPDATEFRAME message to the frame window after creating the 
menu. 





WinPopupMenu 


Displays and processes a floating pop-up menu. 


SYNTAX 


BOOL WinPopupMenu (HWND hwndParent, HWND hwndOwner, 
HWND hwndMenu, LONG x, LONG y, 
ULONG idltem, USHORT fs) 


PARAMETERS 


hwndParent - input 

The handle of the window that will act as the pop-up menu’s parent. 
PM will clip the pop-up menu to the parent’s boundary. Pass HWND_ 
DESKTOP for the pop-up menu to be clipped only to the desktop. 
hwndOwner - input 

The handle of the window that will act as the pop-up menu’s owner. 
The pop-up menu will pass notification messages (WM_COMMAND, 
WM_SYSCOMMAND, WM_INITMENU, WM_MEASUREITEM, WM_ 
DRAWITEM, or WM_HELP) to the owner window. 

hwndMenu - input 

The pop-up menu window’s handle. You must first load or create the 
menu window with WinLoadMenu or WinCreateMenu. 
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x - input 

The x-coordinate (in pixels) of the menu’s lower left corner relative to 

the lower left of the parent window. PM may modify the x-coordinate 

based on the fs argument described below. 

y- input 

The y-coordinate (in pixels) of the menu’s lower left corner relative to 

the lower left of the parent window. PM may modify the x-coordinate 

based on the fs argument described below. 

idItem - input 

An identifier for a menu item on the pop-up menu or one of its sub- 

menus. PM ignores this argument unless you specify PU_POSITION- 

ONITEM or PU_SELECTITEM in the flags. 

fs- input 

A combination of the following flags: 

PU_HCONSTRAIN Ensure that the entire width of the menu is visi- 
ble on the parent window. If you specify this flag, this function mod- 
ifies the x-coordinate. 

PU_KEYBOARD Allow selection with the keyboard. 

PU_MOUSEBUTTONI1 Allow selection with the first mouse button. 

PU_MOUSEBUTTONIDOWN Start menu selection with the first 
mouse button down. This flag is useful if your program displays the 
pop-up menu in response to the user pressing the first mouse but- 
ton. This lets the user select an item without releasing the mouse 
button. Cannot be combined with PU_MOUSEBUTTON2DOWN, 
PU_MOUSEBUTTON3SDOWN, or PU_NONE. 

PU MOUSEBUTTON2 Allow selection with the second mouse but- 
ton. 

PU_MOUSEBUTTON2DOWN Start menu selection with the sec- 
ond mouse button down. This flag is useful if your program displays 
the pop-up menu in response to the user pressing the second mouse 
button. This lets the user select an item without releasing the mouse 
button. Cannot be combined with PU_MOUSEBUTTONIDOWN, 
PU_MOUSEBUTTON3DOWN, or PU_NONE. 

PU _MOUSEBUTTONS Allow selection with the third mouse but- 
ton. 

PU_MOUSEBUTTON3DOWN Start menu selection with the third 
mouse button down. This flag is useful if your program displays the 
pop-up menu in response to the user pressing the third mouse but- 
ton. This lets the user select an item without releasing the mouse 
button. Cannot be combined with PU_MOUSEBUTTONIDOWN, 
PU_MOUSEBUTTON2DOWN, or PU_NONE. 
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PU_NONE Start menu selection with no mouse button down. This is 
the default value and cannot be combined with PU _MOUSEBUT- 
TONIDOWN, PU_MOUSEBUTTON2DOWN, or PU_MOUSEBUTTON- 
3DOWN. 

PU_POSITIONONITEM Change the menu’s coordinates so that 
the menu item identified by zdliem lies under the mouse pointer. 
You must also specify PU_NONE. 

PU_SELECTITEM Preselect the menu item specified by zdliem. 

PU_VCONSTRAIN Ensure that the entire height of the menu is vis- 
ible. If you specify this flag, this function modifies the y-coordinate. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinLoadMenu -160, WinCreateMenu -154 


NOTES 


Before calling this function, you must create or load a menu window 
with WinLoadMenu or WinCreateMenu, which make the menu invisi- 
ble. This function displays the menu and lets the user select items on 
the menu using the mouse or keyboard, based on the flags that you 
specify. 

A pop-up menu generates the same messages as an action bar or 
system menu—for example, the owner window receives WM_COM- 
MAND when the user selects a menu item. 


EXAMPLE 


This example displays a pop-up menu in response to the user pressing 
the first mouse button. Here is a fragment of the resource file: 


MENU IDM_POP 

{ 
MENUITEM “Test 1”, IDM_TEST1 
MENUITEM “Test 2”, IDM_TEST2 
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Here is a fragment of the client window procedure: 


HWND hwndPop; 
case WM_CREATE: 


/* load the menu invisibly */ 

hwndPop = WinLoadMenu 
(WinQueryWindow (hwnd, QW_PARENT ) 
, NULLHANDLE 
, LDM_POP ); 


/* change menu’s ID to prevent conflict with action bar */ 
WinSetWindowUShort (hwndPop, QWS_ID, IDM_POP ); 


return 0; 


case WM_BUTTONI1DOWN: 
{ 

POINTL ptl; 

BOOL fSuccess; 


/* retrieve mouse-click coordinates */ 
SHORTIFROMMP (mpl ); 
SHORT2FROMMP (mpl ); 


Ctl. 


II 


CEL ay 


/* display the pop-up menu. Let user select with keyboard */ 
/* and first mouse button. Ensure entire menu is visible */ 
fSuccess = WinPopupMenu ( 
HWND_DESKTOP 
, hwnd 
, hwndPop 
x Bex .s 
; ptl.y 
, 0 
, PU_KEYBOARD | PU_NONE | PU_MOUSEBUTTON1 | 
PU_HCONSTRAIN | PU_VCONSTRAIN )j; 


we 





@ WinSetMenultemText 





Changes a menu item’s text. 
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SYNTAX 

BOOL WinSetMenultemText (HWND hwndMenu, USHORT id, 
PSZ psz) 

PARAMETERS 


hwndMenu - input 

The top-level menu window’s handle; for example, the action bar. 
id - input 

The menu item’s identifier. 

psz - input 

Pass the new string for the menu item. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_ INVALID _HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinSendMsg -54, WinWindowFromID -322 


NOTES 


This is actually a macro defined in PMWIN.H that issues WinSendMsg 
to send the MM_SETITEMTEXT message to the menu window. 





idlogs 





Presentation Manager program can use a dialog box window to 

display information or to receive user input. A dialog box consists 
of a frame window and child windows, called dialog controls. A dialog 
box is conceptually similar to a standard window except that there is 
no separate client window and the programmer can define the dialog’s 
appearance in a resource script. Most development environments pro- 
vide visual dialog editors to aid in creating the dialog script. In addi- 
tion, to display a dialog, the programmer typically uses the functions 
described in this chapter rather than WinCreateStdWindow. PM pro- 
vides several standard dialog controls including pushbuttons, list 
boxes, and so on. A programmer can also write new dialog control 
window classes. 

The programmer must write a dialog procedure that responds to 
messages from the system and the dialog controls. A dialog procedure 
is similar to a window procedure except that it receives the WM_INIT- 
DLG message instead of WM_CREATE, and should call WinDefDlgProc 
for unprocessed messages instead of WinDefWindowProc. 


Modal and Modeless Dialogs 


If a program displays a modal dialog, PM prevents the dialog’s owner 
window from receiving user input. Thus the user must complete and 
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dismiss the dialog before interacting with the owner window, which is 
typically the top-level frame window of the program. 

If a program displays a modeless dialog, the owner window is not 
disabled. However, PM prevents the modeless dialog from “going be- 
hind” its owner. A modeless dialog is thus quite similar to a standard 
window; its primary advantage is that you can define its appearance is 
the dialog resource script. 


Dialog Coordinates 


To minimize the differences between display resolutions, dialogs use 
dialog coordinates, based on the system font size, instead of pixels. An 
x dialog unit is defined as one-fourth the width of the system font cell, 
while a y dialog unit is one-eighth of the system font cell height. A pro- 
gram can use WinMapDIlgPoints to convert between pixels and dialog 
coordinates. 


Dialog Functions 





WinCheckButton checks or unchecks a radio button or check box (pg 
168). 

WinCreateDlg creates a dialog from a memory template (pg 169). 
WinDefDlgProc provides default processing for dialog procedures (pg 
172). 

WinDeleteLboxItem removes an item from a list box (pg 173). 
WinDismissDlg hides a dialog and ends a modal loop (pg 174). 
WinDIgBox loads and displays a modal dialog (pg 175). 
WinEnableControl enables or disables a dialog control (pg 176). 
WinEnumDIgItem enumerates dialog controls (pg 177). 
WinGetDIigMsg dequeues a dialog message from a message queue (pg 
178). 

WinInsertLboxlItem adds an item to a list box (pg 179). 
WinIsControlEnabled determines if a dialog control is enabled (pg 
180). 

WinLoadDlg loads a dialog from a resource (pg 181). 
WinMapDIgPoints converts dialog coordinates (pg 183). 
WinMessageBox displays a simple modal dialog (pg 184). 
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WinMessageBox2 displays a simple modal or modeless dialog (pg 187). 
WinProcessDlg displays a modal dialog (pg 190). 
WinQueryButtonCheckState determines if a radio button or check 
box is checked (pg 192). 

WinQueryDlgItemShort retrieves an integer from a child window (pg 
192), 

WinQueryDlgItemText retrieves a text string from a child window (pg 
194). 

WinQueryDlgItemTextLength retrieves the length of a child window’s 
text string (pg 195). 

WinQueryLboxCount retrieves the number of items in a list box (pg 
196). 

WinQueryLboxlItemText retrieves an item’s text string from a list box 
(pg 196). 

WinQueryLboxItemTextLength retrieves the length of an item’s text 
string from a list box (pg 197). 

WinQueryLboxSelectedItem retrieves the index of the selected item 
in a list box (pg 198). 

WinSendDlgItemMsg sends a message to a child window (pg 199). 
WinSetDigItemShort assigns an integer to a child window (pg 200). 
WinSetDigItemText assigns a text string to a child window (pg 201). 
WinSetLboxItemText changes the text string of an item in a list box 
(pg 202). 

WinSubstituteStrings is called by PM to let a dialog procedure modify 
dialog text strings as the dialog is created (pg 203). 





WinCheckButton 





Checks or unchecks a radio button or check box. 


SYNTAX 
ULONG WinCheckButton (HWND hwndDig, USHORT id, BOOL /) 


PARAMETERS 

hwndDig - input 

The handle of the dialog containing the check box or radio button. 
id - input 

The window identifier of the check box or radio button window. 

f- input 

Pass TRUE to check the control, FALSE to uncheck it. 
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RETURNS 


Previous check state. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinSendDlgItemMsg -199, WinSendMsg -54, 
WinWindowFromID -322, WinQueryButtonCheckState -192 


NOTES 


This is actually a macro that sends the BM_SETCHECK message to the 
indicated control window. 





WinCreateDlg 


Creates a dialog from a memory template. 


SYNTAX 


HWND WinCreateDlg (HWND hwndParent, HWND hwndOwner, 
PFNWP p/nwp, PDLGTEMPLATE pdigi, 
PVOID pCreate) 


PARAMETERS 


hwndParent - input 

The handle of the window that will act as the dialog’s parent. PM will 
clip the dialog to this window’s boundaries. Pass HWND_DESKTOP for 
the dialog to be clipped to the desktop, or pass HWND_OBJECT to cre- 
ate the dialog invisibly. 

hwndOuwner - input 

The handle of the window that will act as the dialog’s owner. If you 
later use WinProcessDlg to display the dialog modally, PM will disable 
the owner from from receiving user input. If you display the dialog as 
modeless, PM will keep the dialog “on top” of its owner in the stack of 
windows. 

pfnwp - input 

The address of the dialog window procedure. 

pdlgt - input 

The address of a dialog template structure that describes the dialog: 
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typedef struct _~DLGTEMPLATE 
{ 


o* Clow. *¢ 


USHORT cbTemplate; 
USHORT CYpe; 

USHORT codepage; 

USHORT offadlgti; 

USHORT fsTemplateStatus; 
USHORT 1ItemFocus; 
USHORT coffPresParams; 


DLGTITEM adlgti[1]; 
} DLGTEMPLATE; 


cbTemplate The structure’s length in bytes. 

type Reserved; set to zero. 

codepage ‘The dialog’s code page, for example 850. 

offadigti The offset from the beginning of the structure to the first 
dialog item. 

fsTemplateStatus Reserved; set to zero. 

iltemFocus The index in the dialog item structure that will receive 
the initial input focus. If none, set to -l. 

coffPresParams Reserved; set to zero. 

adilgti An array of DLGITEM structures defined below. 


typedef struct _DLGTITEM /* dlgti */ 


{ 


USHORT 
USHORT 
USHORT 
USHORT 
USHORT 
USHORT 
ULONG 
SHORT 
SHORT 
SHORT 
SHORT 
USHORT 
USHORT 
USHORT 


} DLGTITEM; 


fsItemStatus; 
cChildren; 
cchClassName; 
offClassName; 
cchText ; 
OLrrText ; 
LLStyile; 

x; 

Yu 

CIs 

CY; 

103 
offPresParams; 


offCtlData; 
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fsIltemStatus Reserved; set to zero. 

cChildren Number of child windows of this item. 

cchClassName Length of the classname string for this item. Set to 
zero for preregistered classnames, and set the offClassName field to 
the least significant 16 bits of the hexadecimal value of the class- 
name. 

offClassName ‘The offset from the beginning of the DLEGTEMPLATE 
structure to the classname string for this item. If the cchClassName 
field is zero, this field contains the least significant 16 bits of the 
hexadecimal value of the classname. 

cchText Length of the window text string for this item. 

offText The offset from the beginning of the DLGTEMPLATE struc- 
ture to the text string for this item. 

flStyle The item’s window style. 

x The x coordinate for this item in dialog coordinates. 

y The y coordinate for this item in dialog coordinates. 

cx The width of the item in dialog coordinates. 

cy The height of the item in dialog coordinates. 

id ‘The item’s identifier. 

offPresParams Offset from the beginning of the DLGTEMPLATE 
structure to the presentation parameters for this item. 

offCilData Offset from the beginning of the DLGTEMPLATE struc- 
ture to the control data for this item. 

pCreate - input 


The address of the data structure passed to the dialog as message pa- 
rameter 2 in the WM_INITDLG message. Pass NULL if you need no 
create parameters. If you pass create parameters, this pointer must ref- 
erence a structure that has the first two bytes set to the structure’s 
length in bytes. 


RETURNS 


NULLHANDLE if the call failed, the dialog window handle otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_-HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 


SEE ALSO 
WinProcessDlg -190, WinDestroyWindow -25, WinLoadDlg -181 
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NOTES 


A program can use this function to create and display a dialog from a 
memory template. If the dialog template specifies the WS_VIS/BLE 
flag, then this function creates and displays the dialog modelessly. 
Alternatively, a program can create the dialog invisibly, and then use 
WinProcessDlg to display it as a modal dialog. 

To delete the dialog from memory, use WinDestroyWindow. 

The WinLoadDialog function calls DosGetResource followed by 
this function to load a dialog from a resource. 





@ WinDefDlgProc 


Provides default processing for dialog procedures. 


SYNTAX 


MRESULT WinDefDlgProc (HWND hwnd, ULONG msg, MPARAM 
mp1, MPARAM mp2) 


PARAMETERS 

hwnd - input 

The dialog window handle. 
msg - input 

The message identifier. 

mpl - input 

The first message parameter. 
mp2 - input 

The second message parameter. 


RETURNS 


The message result. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 


SEE ALSO 
WinDismissDlg -174 
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NOTES 


A dialog procedure should pass all unprocessed messages to this func- 
tion. 

A dialog procedure can handle the WM_PAINT message by calling 
this function first and then obtaining a cached-micro presentation 
space with WinGetPS (pg 108). 

This function is the same as WinDefWindowProc except that it is- 
sues WinDismissDlg when it processes the WM_CLOSE message. 





WinDeleteLboxitem 


Removes an item from a list box. 


SYNTAX 
LONG WinDeleteLboxItem (HWND hwndLbox, LONG index) 


PARAMETERS 


hwndLbox - input 

The window handle of a list box. 

index - input 

The zero-based index of an item in the list box. 


RETURNS 


The number of items left. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinInsertLboxItem -179, WinQueryLboxCount -196, 
WinQueryLboxItemText -196, WinQueryLboxItemTextLength -197, 
WinQueryLboxSelectedItem -198, WinSetLboxItemText -202 


NOTES 


This is actually a macro that sends LM_DELETEITEM to the list box 
window. 
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@® WinDismissDlg 


Hides a dialog and ends a modal loop. 


SYNTAX 
BOOL WinDismissDlg (HWND hwndDig, ULONG ulResult) 


PARAMETERS 

hwndDilg - input 

The handle of the dialog to dismiss. 
ulResult - input 


An application-defined value that PM returns to WinProcessDlg or 
WinDlgBox. Must be between 0 and 65535. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 


SEE ALSO 


WinCreateDlg -169, WinLoadDlg -181, WinProcessDlg -190, 
WinDlgBox -175, WinDestroyWindow -25 


NOTES 


This function operates differently on modal and modeless dialogs. If 
the dialog is modeless, this function simply hides the dialog. If the dia- 
log was modally displayed with WinDlgBox or WinProcessDlg, this 
function hides the dialog, reenables the owner window, and breaks out 
of the modal loop, returning ulResult to WinDlgBox or WinProcessDlg. 
Thus this function is required for modal dialogs, but not for modeless. 
Many dialog window procedures issue this function in response to the 
WM_COMMAND message generated by OK or Cancel pushbuttons, 
and return the button identifier as ulResult. 

This function doesn’t destroy the dialog and remove it from mem- 
ory; the program must issue WinDestroyWindow (note that Win- 
DigBox issues WinDestroyWindow internally). 
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@® WinDigBox 
Loads and displays a modal dialog. 


SYNTAX 


ULONG WinDIlgBox (HWND hwndParent, HWND hwndOwner, 
PFNWP pfnwp, HMODULE hmod, ULONG id, 
PVOID pCreate) 


PARAMETERS 


hwndParent - input 

The handle of the window that will act as the dialog’s parent. PM will 
clip the dialog to this window's boundaries. Pass HWND_DESKTOP for 
the dialog to be clipped to the desktop, or pass HWND_OBJECT to cre- 
ate the dialog invisibly. 

hwndOwner - input 

The handle of the window that will act as the dialog’s owner. PM will 
disable the owner from receiving user input. 

pfnwp - input 

The address of the dialog window procedure. 

hmod - input 

The module handle of the DLL containing the dialog resource, or 
NULLHANDLE if the dialog resource is bound to the executable. You 
can use DosLoadModule or DosQueryModuleHandle to retrieve a 
DLL’s module handle. 

id - input 

The dialog resource identifier assigned in the dialog script. 

pCreate - input 

The address of data structure passed to the dialog as message parame- 
ter 2 in the WM_INITDLG message. Pass NULL if you need no create 
parameters. If you pass create parameters, this pointer must reference 
a structure that has the first two bytes set to the structure’s length in 
bytes. 


RETURNS 


The ulResult value from WinDismissDlg or DJD_ERROR (OXFFFF) if an 
error occurred. 
Possible returns from WinGetLastError: 


Oxl001 - PMERR_INVALID_HWND 
Ox100a - PMERR_ RESOURCE_NOT_FOUND 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 


SEE ALSO 


WinLoadDlg -181, WinProcessDlg -190, WinDestroyWindow -25, 
WinCreateDlg -169, WinDismissDlg -174 


NOTES 


This function loads and modally displays a dialog. It is equivalent to 
calling WinLoadDlg, WinProcessDlg, and WinDestroyWindow consec- 
utively. 

This call does not return until the dialog is dismissed with Win- 
DismissDlg. 





@ WinEnableControl 





Enables or disables a dialog control. 


SYNTAX 
BOOL WinEnableControl (HWND hwndDig, USHORT zd, BOOL /) 


PARAMETERS 

hwndDig - input 

The handle of the dialog containing the control. 

id - input 

The window identifier of the control window. 

f- input 

Pass TRUE to enable the control, FALSE to disable it. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinEnableWindow -85, WinWindowFromID -180, 
WinIsControlEnabled -322 
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NOTES 


This is actually a macro that determines the control’s window handle 
with WinWindowFromID, and then calls WinEnableWindow. 





WinEnumDigitem 


Enumerates dialog controls. 


SYNTAX 

HWND WinEnumDigltem (HWND hwndDig, HWND hwndChild, 
ULONG u/) 

PARAMETERS 


hwndDig - input 

The dialog’s window handle. 

hwndChild - input 

The handle of a dialog control window. 

ul - input 

One of the following values. This function treats the dialog script as an 
ordered list. A group of dialog controls is formed by assigning the first 
group member the WS_GROUP style. 


EDI_FIRSTGROUPITEM Return the handle of the first window in 
the same group as hwndChild. 

EDI _FIRSTTABITEM Return the handle of the first window in the 
dialog that has the WS_TABSTOP style. Ignores hwndChild. 

EDI_ LASTGROUPITEM Return the handle of the last window in 
the same group as hwndChild. 

EDI_LASTTABITEM Return the handle of the last window in the di- 
alog that has the WS_TABSTOP style. Ignores hwndChild. 

EDI NEXTGROUPITEM Return the handle of the next member of 
the group after hwndChild. If hwndChild is the last member, this func- 
tion returns the handle of the first member (it wraps around). 

EDI_ NEXTTABITEM Return the handle of the first window that has 
the WS_TABSTOP style after hwndChild . If there is none, this func- 
tion returns the handle of the first window (it wraps around). 

EDI_PREVGROUPITEM Return the handle of the previous member 
of the group before hwndChild. If hwndChild is the first member, this 
function returns the handle of the last member (it wraps around). 
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EDI PREVTABITEM Returns the handle of the window that has the 
WS_TABSTOP style before hwndChild . If there is none, this function 
returns the handle of the last window (it wraps around). 


RETURNS 


A dialog control window handle or NULLHANDLE. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 


SEE ALSO 
WinWindowFromID -322, WinBeginEnum Windows -274 


NOTES 


A program can call this function in a loop to enumerate the child con- 
trol windows in the dialog. 





@ WinGetDigMsg 


Dequeues a dialog message from a message queue. 


SYNTAX 
BOOL WinGetDlgMsg (HWND hwndDig, PQMSG pqmsg) 


PARAMETERS 
hwndDig - input 
The handle of a modeless dialog. 
pqmsg - output 
The address of a QMSG structure: 
typedef struct _OMSG /* qmsg */ 
{ 

HWND = hw; 

ULONG msg; 

MPARAM mp1; 

MPARAM mp2; 

ULONG time; 
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POINTL ptl; 
ULONG reserved; 
} QMSG; 


hwnd The handle of the window receiving the message. 

msg ‘The message identifier. 

mpl ‘The first message parameter. 

mp2 ‘The second message parameter. 

time ‘The time the message was generated. 

ptl The mouse pointer coordinates at the time the message was gen- 
erated. 

reserved Reserved. 


RETURNS 


TRUE if the message was not WM_QUIT, FALSE if the message was 
WM_QUIT or the dialog was dismissed. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID_ HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 


SEE ALSO 
WinCreateDlg -169, WinLoadDlg -181 


NOTES 


Some programming languages cannot support reentrant dialog win- 
dow procedures for modal dialogs. A program written in such a lan- 
guage can call this function in a loop to display a modal dialog. The 
first time through the loop, this function will disable the dialog’s 
owner window. 





WinlnsertLboxltem 





Adds an item to a list box. 


SYNTAX 
LONG WinInsertLboxItem (HWND hwndLbox, LONG index, PSZ psz) 
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PARAMETERS 

hwndLbox - input 

The window handle of a list box. 

index - input 

Pass the zero-based index of where to place the item in the list box or 
one of the following: 


LIT_END Append the new item. 

LIT_SORTASCENDING Insert the new item, sorting it alphabeti- 
cally, in ascending order. 

LIT_SORTDESCENDING Insert the new item, sorting it alphabeti- 
cally, in descending order. 

psz - input 

Pass the address of a string containing the new item’s text. The list box 

makes an internal copy of this text string. 


RETURNS 


The new item’s index, or LIT ERRORif an errror occurred. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinDeleteLboxItem -173, WinQueryLboxCount -196, 
WinQueryLboxItemText -196, WinQueryLboxItemTextLength -197, 
WinQueryLboxSelectedItem -198, WinSetLboxItemText -202 


NOTES 


This is actually a macro that sends LM_INSERTITEM to the list box 
window. 





@® WinlsControlEnabled 


Determines if a dialog control is enabled. 


SYNTAX 
BOOL WinlIsControlEnabled (HWND hwndDig, USHORT id) 
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PARAMETERS 

hwndDig - input 

The handle of the dialog containing the control. 
id - input 

The window identifier of the control window. 


RETURNS 
TRUE if control is enabled, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinIsWindowEnabled -93, WinWindowFromID -322, 
WinEnableControl -176, WinEnableWindow -85 


NOTES 


This is actually a macro that determines the control’s window handle 
with WinWindowFromID, and then calls WinIsWindowEnabled. 





WinLoadDlg 


Loads a dialog from a resource. 


SYNTAX 


HWND WinLoadDlg (HWND hwndParent, HWND hwndOwner, 
PENWP pfnwp, HMODULE hmod, ULONG id, 
PVOID pCreaite) 


PARAMETERS 


hwndParent - input 

The handle of the window that will act as the dialog’s parent. PM will 
clip the dialog to this window’s boundaries. Pass HWND_DESKTOP for 
the dialog to be clipped to the desktop, or pass HWND_OBJECT to cre- 
ate the dialog invisibly. 

hwndOwner - input 

The handle of the window that will act as the dialog’s owner. If you 
later use WinProcessDlg to display the dialog modally, PM will disable 
the owner from from receiving user input. If you display the dialog as 
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modeless, PM will keep the dialog “on top” of its owner in the stack of 
windows. 

pfnwp - input 

The address of the dialog window procedure. 

hmod - input 

The module handle of the DLL containing the dialog resource, or 
NULLHANDLE if the dialog resource is bound to the executable. You 
can use DosLoadModule or DosQueryModuleHandle to retrieve a 
DLL’s module handle. 

id - input 

The dialog resource identifier assigned in the dialog script. 

pCreate - input 

The address of the data structure passed to the dialog as message pa- 
rameter 2 in the WM_INITDLG message. Pass NULL if you need no 
create parameters. If you pass create parameters, this pointer must ref- 
erence a structure that has the first two bytes set to the structure’s 
length in bytes. 


RETURNS 
NULLHANDLE if the call failed, the dialog window handle otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 


SEE ALSO 
WinProcessDlg -190, WinDestroyWindow -25, WinCreateDlg -169 


NOTES 


A program can use this function to create and display a dialog from a 
resource. If the dialog script specifies the WS_VIS/BLE flag, then this 
function creates and displays the dialog visibly, as a modeless dialog. 
Alternatively, a program can create the dialog invisibly, and then use 
WinProcessDlg to display it as a modal dialog. 

To delete the dialog from memory, use WinDestroyWindow. 

This function internally calls DosGetResource followed by Win- 
CreateDlg to load a dialog from a resource. 
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@ WinMapDigPoints 
Converts dialog coordinates. 


SYNTAX 


BOOL WinMapDlgPoints (HWND hwndDig, PPOINTL aptl, ULONG 
cPoints, BOOL fOptions) 


PARAMETERS 

hwndDig - input 

The handle of the dialog window. 

aptl - input/output 

Pass the address of an array of POINTL data structures containing the 

coordinates to convert. 

cPoints - input 

The number of points in the array. 

fOptions - input 

TRUE Convert the points to window coordinates from dialog coor- 
dinates. 

FALSE Convert the points from dialog coordinates to window coor- 
dinates. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 


SEE ALSO 
WinMapWindowPoints -282, WinDefDlgProc -172 


NOTES 


To minimize the differences between display resolutions, dialogs use 
dialog coordinates, based on the system font size, instead of pixels. An 
x dialog unit is defined as one fourth the width of the system font cell, 
while a y dialog unit is one-eighth of the system font cell height. A pro- 
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gram can use this function to convert between window coordinates 
(pixels) and dialog coordinates. 

The apil array is used for both input and output. That is, before 
calling this function, you should initialize the points in the array; this 
function will place the converted coordinates in the same array. 

This function is useful for programs that wish to draw to the dialog 
window. See WinDefDlgProc for further information. 





WinMessageBox 


Displays a simple modal dialog. 


SYNTAX 


ULONG WinMessageBox (HWND hwndParent, HWND hwndOwner, 
PSZpszText, PSZ pszTitle, ULONG 2d, 
ULONG /l) 


PARAMETERS 


hwndParent - input 

The handle of the window that will act as the dialog’s parent. PM will 
clip the message box to this window’s boundaries. Pass HWND_DESK- 
TOP for the box to be clipped to the desktop. 

hwndOwner - input 

The handle of the window that will act as the message box’s owner. PM 
will disable the owner from receiving user input. 

pszText - input 

The text to be displayed in the message box. The text can contain new- 
line characters. | 

pszTitle - input 

The message box title. The title should be no more than 40 characters. 
If you pass NULL, the message box will display a title of “Error.” 

id - input 

The message box identifier used by the help system. If you have no spe- 
cific help screen for the message box, you can pass zero. 

fl- input 

A combination of flags that configure the message box. You may 
choose one or more from each category described below. 


Button Type—choose one flag from this category: 


MB_ABORTRETRYIGNORE Box contains Abort, Retry, and Cancel 
buttons. 
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MB CANCEL Box contains Cancel button. 

MB _ ENTER Box contains Enter button. 

MB ENTERCANCEL = Box contains Enter and Cancel buttons. 
MB OK Box contains OK button. This is the default. 

MB OKCANCEL = Box contains OK and Cancel buttons. 
MB_RETRYCANCEL Box contains Retry and Cancel buttons. 
MB_YESNO Box contains Yes and No buttons. 

MB YESNOCANCEL Box contains Yes, No, and Cancel buttons. 


Icon—choose one flag from this category: 


MB_ CRITICAL Box contains an icon displaying a slashed circle. 

MB_CUACRITICAL Box contains an icon displaying a slashed circle 
(same as MB_CRITICAL). 

MB _CUANOTIFICATION No icon (same as MB_NOIJCON). 

MB CUAWARNING | Box contains an icon displaying the letter “1” in 
a triangle. 

MB_ERROR Box contains a stop sign icon. 

MB_ICONASTERISK Box contains an asterisk icon. 

MB _ICONEXCLAMATION Box contains an exclamation point 
icon. 

MB ICONHAND | Box contains a hand icon. 

MB_ICONQUESTION Box contains a question mark icon. 

MB_INFORMATION _ Box contains an icon displaying the letter “1” 
in a square box. 

MB NOICON Box contains no icon. This is the default. 

MB_QUERY Box contains a question mark icon (same as MB_ICON- 
QUESTION). 

MB_WARNING Box contains an icon displaying an exclamation 
point in a square box. 


Intial default button—choose one flag from this category: 


MB_DEFBUTTONI The Enter key invokes the first button. This is 
the default. 

MB _DEFBUTTON2 ‘The Enter key invokes the second button. 

MB DEFBUTTON3 The Enter key invokes the third button. 


Miscellaneous—Choose more than one flag from this category: 


MB APPLMODAL The message box disables its owner and all of the 
owner’s descendants. This is the default. Cannot be combined with 
MB_SYSTEMMODAL. 

MB_HELP ‘The message box contains a Help button that generates 
the WM_HELP message. 
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MB MOVEABLE The message box contains a title bar. 
MB SYSTEMMODAL The message box disables all windows. 
Cannot be combined with MB_APPLMODAL. 


RETURNS 


A code that specifies the button pressed to dismiss the message box, or 
MBID_ERROR (OXFFFF) if an error occurred. 


MBID_ABORT User pressed Abort button. 
MBID CANCEL User pressed Cancel button. 
MBID_ ENTER User pressed Enter button. 
MBID IGNORE User pressed Ignore button. 
MBID NO User pressed No button. 

MBID_ OK User pressed OK button. 
MBID_RETRY User pressed Retry button. 
MBID_YES User pressed Yes button. 


Possible returns from WinGetLastError: 


Oxl001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 


SEE ALSO 
WinDlgBox -175, WinMessageBox2 -187 


NOTES 


A message box is essentially a modal dialog box with a PM-provided di- 
alog procedure. Therefore, it is useful to display a message to the user 
and get a response while writing minimal code. However, you cannot 
customize its appearance to the extent that you can a modal dialog. 

There must be a message queue created on any thread to display 
a message box. 

PM always centers the message box on the screen and brings it to 
the top of the stack of windows. 

PM will size the message box based on the title text and the text 
string. The minimim size (regardless of the text and title strings) for 40 
characters wide and two lines of text. The maximum height is approx- 
imately two-thirds of the screen height. 

PM will attempt to word-wrap the text string, but you can force a 
new line by embedding the new-line character in the text string. 
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@ WinMessageBox2 


Displays a simple modal or modeless dialog. 


SYNTAX 


ULONG WinMessageBox2 (HWND hwndParent, HWND hwndOwner, 
PSZ pszText, PSZ pszTitle, ULONG 2d, 
PMB2INFO pmb2i) 


PARAMETERS 


hwndParent - input 

The handle of the window that will act as the dialog’s parent. PM will 
clip the message box to this window’s boundaries. Pass HWND_DESK- 
TOP for the box to be clipped to the desktop. 

hwndOwner - input 

The handle of the window that will act as the message box’s owner. PM 
will disable the owner from receiving user input. 

pszText - input 

The text to be displayed in the message box. The text can contain new- 
line characters. 

pszTitle - input 

The message box title. The title should be no more than 40 characters. 
If you pass NULL, the message box will display a title of “Error.” 

id - input 

The message box identifier used by the help system. If you have no spe- 
cific help screen for the message box, you can pass zero. 

pmb2i - input 

Pass the address of an MB2INFO structure: 


typedef struct _~MB2INFO 
{ 


ULONG cb; 
HPOINTER hIcon; 
ULONG cButtons; 


ULONG f1Style; 
HWND hwndNotify; 
MB2D mb2da[1]; 

} MB2INFO; 


cb The structure’s length, in bytes. 
hIicon The handle of an icon or pointer. Pass NULLHANDLE unless 
you specify MB_CUSTOMICON in the /lStyle field. 
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cButtons The number of buttons. Each button requires an MB2D 
structure in the array at the end of this structure. 

fIStyle A combination of the following flags: 

Icon—Choose one flag from this category: 


MB_CRITICAL Box contains an icon displaying a slashed circle. 

MB_CUACRITICAL Box contains an icon displaying a slashed cir- 
cle (same as MB_CRITICAL). 

MB CUANOTIFICATION No icon (same as MB_NOJCON). 

MB_CUAWARNING _ Box contains an icon displaying the letter “i” 
in a triangle. 

MB_ERROR Box contains a stop sign icon. 

MB ICONASTERISK Box contains an asterisk icon. 

MB_ICONCUSTOM Box draws the icon specified by the Alcon 
field. 

MB_ICONEXCLAMATION Box contains an exclamation point 
icon. 

MB ICONHAND Box contains a hand icon. 

MB ICONQUESTION Box contains a question mark icon. 

MB_INFORMATION Box contains an icon displaying the letter 
“7” in a square box. 

MB NOICON Box contains no icon. This is the default. 

MB_QUERY Box contains a question mark icon (same as MB_ 
ICONQUESTION). 

MB _ WARNING §Box contains an icon displaying an exclamation 
point in a square box. 


Miscellaneous—Choose more than one flag from this category: 


MB_APPLMODAL The message box disables its owner and all of 
the owner’s descendants. This is the default. 

MB MOVEABLE The message box contains a title bar. 

MB NONMODAL The message box is displayed modelessly. 
WinMessageBox2 returns immediately with the message box’s 
window handle. The hwndNotify window will receive the WM_MS- 
GBOXINIT and WM_MSGBOXDISMISS messages. Cannot be com- 
bined with MB_APPLMODAL or MB_SYSTEMMODAL. 

MB_SYSTEMMODAL The message box disables all windows. Can- 
not be combined with MB_APPLMODAL or MB_NONMODAL. 


hwndNotify Pass the window handle of the window to be notified for 
a modeless message box. 
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mb2d_ An array of MB2D structures, one for each button on the mes- 
sage box: 


#define MAX_MBDTEXT 70 


typedef struct _MB2D 

{ 
CHAR achText [MAX_MBDTEXT + 1]; 
ULONG idButton; 
LONG Listyle: 

} MB2D; 


achText ‘The text string for the button. 

idButton The button window identifier. If you specify MB_NON- 
MODAL, the Notify window receives this button ID in message para- 
meter 2. 

flStyle A combination of BS_ (button style) values. 


RETURNS 


A code that specifies the button pressed to dismiss the message box, or 
MBID_ERROR (OXFFFF) if an error occurred. If you specify the MB_ 
NONMODAL flag, the message box’s window handle is returned. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INGL_WINDIALOGS 


SEE ALSO 
WinDlgBox -175, WinMessageBox -184, WinDestroyWindow -25 


NOTES 


This function differs from WinMessageBox in that you can specify the 
number of buttons, the button text, load a custom icon, and display 
the message box modelessly. If you display the box modelessly, the 
Notify window must destroy the message box when it receives the 
WM_MSGBOXDISMISS message. 

There must be a message queue created on any thread to display 
a message box. 
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EXAMPLE 


This sample creates a modeless message box, with two buttons and an 
icon loaded from the program’s resources. 


#define ID_BUTTON1 200 
#define ID_BUTTON2 201 
PMB2INFO pmb2i; // pointer to messagebox2 structure 
ULONG cb; // structure size 
// allocate memory for the info structure 
cb = sizeof (MB2INFO ) + sizeof (MB2D ); 
pmb2i = (PMB2INFO)malloc (cb ); 
// initialize the info structure 
piibZil=Scb = ch: 
pmb2i->hIcon = WinLoadPointer ( HWND_DESKTOP, NULLHANDLE 
, LDF_MAIN ); 
pmb2i->cButtons = 2; 
pmb2i->f1Style = MB_CUSTOMICON | MB MOVEABLE | MB _NONMODAL; 
pmb2i->hwndNotify = hwndClient; 


strcepy (pmb2i->mb2d[0].achText, “Button 1” ); 
pmb2i->mb2d[0].idButton = ID _BUTTON1; 
pmb2i->mb2d[0].f1Style = 0; 


strcpy (pmb2i->mb2d[1].achText, “Button 2” ); 
pmb2i->mb2d[1].idButton = ID_BUTTON2; 
pmb2i->mb2d[1].f1Style = BS_DEFAULT; 
// display the message box 
hwndMsgBox = WinMessageBox2 (HWND_DESKTOP, hwndFrame, “Test” 
“Message”, 0, pmb2i ); 


free (pmb2i ); 





@ WinProcessDlg 


Displays a modal dialog. 


SYNTAX 
ULONG WinProcessDIlg (HWND hwndDig) 
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PARAMETERS 
hwndDig - input 
The dialog window handle. 


RETURNS 


The ulResult value from WinDismissDlg or DID_ERROR (OXFFFF) if an 
error occurred. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 


SEE ALSO 


WinCreateDlg -169, WinLoadDlg -181, WinDlgBox -175, 
WinDismissDlg -174, WinQueryWindowUShort -298, 
WinSetWindowUShort -317 


NOTES 


This function enters a modal loop, disabling the owner window of the 
dialog from receiving user input and does not return until the dialog 
is dismissed with WinDismissDlg. It essentially converts a modeless dia- 
log to a modal dialog. 

Before issuing this function, the program must first create the di- 
alog using WinCreateDlg or WinLoadDlg. ‘To remove the dialog, use 
WinDestroyWindow. Because this function makes the dialog visible, 
you normally create the dialog invisible. Note that WinDlgBox does 
the same as WinLoadDlg, WinProcessDlg, and WinDestroyWindow 
combined. 

One use of this function is to let programs maintain commonly 
used dialogs in memory (WinDlgBox destroys the dialog when it’s dis- 
missed). The program can load or create the dialog invisibly at startup 
and destroy the dialog when the program exits. Whenever the user re- 
quests the dialog, the program can issue WinProcessDlg to make the di- 
alog visible, and the WinDismissDlg function will hide the dialog when 
the user finishes. For this technique to work properly, the program also 
needs to modify a bit in the dialog’s window data structure each time: 


USHORT usFlags; // frame window flags 

usFlags = WinQueryWindowUShort ( hwndDlg, QWS_FLAGS ); 
usFlags &= -FF_DLGDISMISSED; 

WinSetWindowUShort ( hwndDlg, QWS_FLAGS, usFlags ); 
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@ WinQueryButtonCheckState 


Determines if a radio button or check box is checked. 


SYNTAX 

USHORT WinQueryButtonCheckState (HWND hwndDig, 
USHORT 7d) 

PARAMETERS 


hwndDlg - input 

The handle of the dialog containing the check box or radio button. 
id - input 

The window identifier of the check box or radio button window. 


RETURNS 
TRUE if the control is checked, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinSendDlgItemMsg -199, WinSendMsg -54, 
WinWindowFromID -322, WinCheckButton -168 


NOTES 


This is actually a macro that sends the BM_QUERYCHECK message to 
the indicated control window. 





@ WinQueryDigitemShort 


Retrieves an integer from a child window. 


SYNTAX 


BOOL WinQueryDlgItemShort (HWND hwndDig, ULONG 7d, 
PSHORT ps, BOOL /fSigned) 
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PARAMETERS 

hwndDilg - input 

The handle of the parent window containing the child window to 
query. 

id - input 

The window identifier of the child window. 

ps - output 

Pass the address of a SHORT or USHORT variable that this function 
will fill in. 

Signed - input 

Pass TRUE if you want a signed number, FALSE if unsigned. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 


SEE ALSO 


WinSetDlgItemShort -200, WinQueryDlgItemText -194, 
WinQueryWindowText -295, WinWindowFromID -322 


NOTES 


This function sends the child window a WM_QUERYWINDOWPARAMS 
message to read the text from the child window, and then attempts to 
convert the text to an integer. This function is roughly equivalent to: 


hwndChild = WinWindowFromID ( hwndDlg, id ); 
cb = WinQueryWindowTextLen ( hwndChild ); 
pez = mallo¢ ( ¢b ); 

WinQueryWindowText ( hwndChild, cb, psz ); 
result = _atoi ( psz ); 

Pree (psz); 


// result contains the retrieved integer 
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@ WinQueryDigitemText 


Retrieves a text string from a child window. 


SYNTAX 


ULONG WinQueryDlgItemText (HWND hwndDig, ULONG 2d, 
LONG cbMax, PSZ psz) 


PARAMETERS 

hwndDig - input 

The handle of the parent window containing the child window to 
query. 

id - input 

The window identifier of the child window. 

cbMax - input 

The maximum length of the returned string. This function always in- 
serts a null terminator at the end of the returned string, and will trun- 
cate the string if required. 

psz - output 

Pass the address of a string, that this function fills in. 


RETURNS 


The length of the returned string, or zero if an error occurred. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_ INVALID _HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 


SEE ALSO 


WinQueryDlgItemTextLength -195, WinQueryWindowText -295, 
WinWindowFromID -322 


NOTES 


This function sends the child window a WM_QUERYWINDOWPARAMS 
message to read the text from the child window. This function is 
roughly equivalent to: 


hwndChild = WinWindowFromID ( hwndDlg, id ); 
cb = WinQueryWindowTextLen ( hwndChild ); 


Dialogs 195 


psz = mallee ( ch )s 
WinQueryWindowText ( hwndChild, cb, psz ); 


free (psz); 





WinQueryDlgitem TextLength 


Retrieves the length of a child window’s text string. 


SYNTAX 
LONG WinQueryDlgItemTextLength (HWND hwndDig, ULONG 7d) 


PARAMETERS 

hwndDilg - input 

The handle of the parent window containing the child window to 
query. 

id - input 

The window identifier of the child window. 

RETURNS 


The text length, or zero if an error occurred. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 


SEE ALSO 
WinQueryWindowTextLen -296, WinWindowFromID -322 


NOTES 


This function sends the child window a WM_QUERYWINDOWPARAMS 
message to read the text length from the child window. This function 
is roughly equivalent to: 


hwndChild = WinWindowFromID (hwndDlg, id ); 
cb = WinQueryWindowTextLen (hwndChild ); 
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@ WinQueryLboxCount 


Retrieves the number of items in a list box. 


SYNTAX 
LONG WinQueryLboxCount (HWND hwndLbox) 


PARAMETERS 
hwndLbox - input 
The window handle of a list box. 


RETURNS 


The number of items in the list box, or LJT_ERRORif an error occurred. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinDeleteLboxItem -173, WinInsertLboxItem -179, 
WinQueryLboxItemText -196, WinQueryLboxItemTextLength -197, 
WinQueryLboxSelectedItem -198, WinSetLboxItemText -202 


NOTES 


This is actually a macro that sends LM_QUERYITEMCOUNT to the list 
box window. 





@ WinQueryLboxitemText 


Retrieves an item’s text string from a list box. 


SYNTAX 


LONG WinQueryLboxItemText (HWND hwndLbox, LONG index, 
PSZ pszOut, SHORT cchMax) 
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PARAMETERS 


hwndLbox - input 

The window handle of a list box. 

index - input 

The zero-based index of an item in the list box. 

pszOut - output 

Pass the address of a string to which this function writes. 
cchMax - input 

The maximum number of bytes that will fit in the output string. 


RETURNS 
The number of characters copied, or zero if an error occurred. 


Possible returns from WinGetLastError: 


Ox1001 - PMERR_ INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinDeleteLboxItem -173, WinInsertLboxItem -179, 
WinQueryLboxCount -196, WinQueryLboxItemTextLength -197, 
WinQueryLboxSelectedItem -198, WinSetLboxItemText -202 


NOTES 


This is actually a macro that sends LM_QUERYITEMTEXT to the list 
box window. You can call WinQueryLboxItemTextLength to deter- 
mine the amount of storage required for the output string. 





WinQueryLboxitemTextLength 


Retrieves the length of an item’s text string from a list box. 


SYNTAX 

LONG WinQueryLboxItemTextLength (HWND hwndLbox, LONG 
index) 

PARAMETERS 


hwndLbox - input 
The window handle of a list box. 
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index - input 
The zero-based index of an item in the list box. 


RETURNS 


The length of the specified item’s text string, or zero if an error Oc- 
curred. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_ INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinDeleteLboxItem -173, WinInsertLboxItem -179, 
WinQueryLboxCount -196, WinQueryLboxItemText -196, 
WinQueryLboxSelectedItem -198, WinSetLboxItemText -202 


NOTES 


This is actually a macro that sends LM_QUERYITEMTEXTLENGTH to 
the list box window. 





@ WinQueryLboxSelecteditem 


Retrieves the index of the selected item in a list box. 


SYNTAX 
LONG WinQueryLboxSelectedItem (HWND hwndLbox) 


PARAMETERS 


hwndLbox - input 
The window handle of a list box. 


RETURNS 


The zero-based index of the selected item, LJT_ NONE if no items are 
selected, LIT_ERROR if an error occurred. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinDeleteLboxItem -173, WinInsertLboxItem -179, 
WinQueryLboxCount -196, WinQueryLboxItemText -196, 
WinQueryLboxItemTextLength -197, WinSetLboxItemText -202 


NOTES 


This is actually a macro that sends LM_QUERYSELECTION to the list 
box window. This function only works on single-selection list boxes. 





WinSendDigitemMsg 


Sends a message to a child window. 


SYNTAX 


MRESULT WinSendDligItemMsg (HWND hwndDig, ULONG id, 
ULONG msgid, MPARAM mp1, 
MPARAM mp2) 


PARAMETERS 

hwndDig - input 

The handle of the parent window containing the child window to 
query. 

id - input 

The window identifier of the child window. 
msgid - input 

The message identifier. 

mpI - input 

The first message parameter. 

mp2 - input 

The second message parameter. 


RETURNS 


The message result. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 


SEE ALSO 
WinSendMsg -54, WinWindowFromID -322, WinPostMsg -44 


NOTES 


This function is equivalent to: 


hwndChild = WinWindowFromID ( hwndDlg, id ); 
mr = WinSendMsg ( hwndChild, msgid, mpl, mp2 ) 





@® WinSetDigitemShort 


Assigns an integer to a child window. 


SYNTAX 


BOOL WinSetDlgItemShort (HWND hwndDig, ULONG zd, USHORT 
us, BOOL /fSigned) 


PARAMETERS 

hwndDig - input 

The handle of the parent window containing the child window to query. 
id - input 

The window identifier of the child window. 

us - input 

The integer to assign. 

Signed - input 

Pass TRUE if us is a signed number, FALSE if unsigned. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 
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SEE ALSO 


WinQueryDlgItemShort -192, WinSetWindowText -315, 
WinWindowFromID -322 


NOTES 


This function attempts to convert the integer to a string and then 
sends the child window a WM_SETWINDOWPARAMS message to assign 
the text string. This function is roughly equivalent to: 


hwndChild = WinWindowFromID (hwndDlg, id ); 
psz = malloc (255 ); 

_itoa (us, psz, 10 ); 

WinSetWindowText (hwndChild, psz ); 


free (psz ); 





WinSetDlgltem Text 


Assigns a text string to a child window. 


SYNTAX 
BOOL WinSetDlgItemText (HWND hwndDig, ULONG id, PSZ psz) 


PARAMETERS 

hwndDig - input 

The handle of the parent window containing the child window to 
query. 

id - input 

The window identifier of the child window. 

psz - input 

The text string to assign. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDIALOGS 
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SEE ALSO 


WinQueryDlgItemText -194, WinSetDlgItemShort -200, 
WinSetWindow Text -315, WinWindowFromID -322 


NOTES 


This function sends the child window a WM_SETWINDOWPARAMS 
message to assign the text string. This function is roughly equivalent to: 


hwndChild = WinWindowFromID (hwndDlg, id ); 
WinSetWindowText (hwndChild, psz ); 





@ WinSetLboxlitemText 


Changes the text string of an item in a list box. 


SYNTAX 
BOOL WinSetLboxItemText (HWND hwndLbox, LONG index, PSZ psz) 


PARAMETERS 


hwndLbox - input 

The window handle of a list box. 

index - input 

The zero-based index of an item in the list box. 

psz- input 

Pass the address of a string containing the item’s new text. The list box 
makes an internal copy of this text string. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 

WinDeleteLboxItem -173, WinInsertLboxItem -179, 
WinQueryLboxCount -196, WinQueryLboxItemText -196, 
WinQueryLboxItemTextLength -197, WinQueryLboxSelectedItem -198 
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NOTES 


This is actually a macro that sends LM_SETITEMTEXT to the list box 
window. 





WinSubstituteStrings 


Called by PM to let a dialog procedure modify dialog text strings as the 
dialog is created. 


SYNTAX 

LONG WinSubstituteStrings (HWND hwnd, PSZ pszSrc, LONG cbDest, 
PSZ pszDest) 

PARAMETERS 

hwnd - input 


The dialog window handle. 

pszSre - input 

The input string. 

cbDest - input 

The length of the destination string. 
pszDest - output 

The output string. 


RETURNS 


Length of the destination string, or zero if unsuccessful. 
Possible returns from WinGetLastError: 
0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCGL_WINDIALOGS 


NOTES 


When a dialog is created from a script, if any of the text strings contain 
a substring of form “%n,” where n ranges from 1-9, PM issues this func- 
tion, which sends a WM_SUBSTITUTESTRING message to the dialog 
window procedure. The dialog function can return a pointer to a 
string that PM inserts into the source string, replacing the “%on.” This 
technique lets a dialog determine the text strings at runtime rather 
than compile time. 


©10 


Standard Dialogs 


204 





tarting in version 1.3, Presentation Manager contains two standard 

dialogs that programs can display to let the user choose file names 
and fonts. ‘This chapter documents the functions for these standard di- 
alogs. They are easy to code, yet powerful and flexible, and save devei- 
opers from creating their own dialogs for file names and fonts. 


Customizing the Dialogs 


Both standard dialogs provide for customization. First, both provide 
many flag options that let you control the dialogs’ behavior and ap- 
pearance. If you need to customize them more than the options al- 
low—for example, adding new dialog controls—then you can create 
your own dialog resource and subclass the built-in dialog window pro- 
cedures. 

If you decide to create your own dialog resource, your custom dia- 
log script must have all of the same controls as the standard dialog, and 
the controls must have the same identifiers as they do in the standard 
dialog. If you don’t want part of a standard dialog in your custom dia- 
log, you should define that part in the dialog, but make it invisible 
(that is, do not assign the WS_VISIBLE flag). You can also add your own 
new controls. The standard controls are listed in the Tables 10.1 and 
10.2 (from PMSTDDLG.H): 
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Table 10.1 File Dialog 


Dialog Control Symbolic Name Value Notes 


Save text string DID_FILENAME_TXT = 257 


File name entry field DID_FILENAME_ED 258 Single line entry 


field 


Drive text string DID_DRIVE_TXT 259 
Drive combo box DID_DRIVE_CB 260 Drop-down list 
File Type text string DID_FILTER_TXT 261 
File type combo box DID_FILTER_CB 262 Drop-down list 


Directory text string 


DID_DIRECTORY_TXT 263 


Directory list box DID_DIRECTORY_LB 264 — Single selection, 
ownerdrawn 

Files text DID_FILES TXT 265 

Files list box DID_FILES LB 266 = Single selection 

Help pushbutton DID_HELP_PB 267 Help style, no 
pointer focus 

Apply pushbutton DID_APPLY_PB 268 

OK pushbutton DID_OK_PB 1 Default style 

Cancel pushbutton DID_CANCEL_PB 2 

Table 10.2 Font Dialog 

Dialog Control Symbolic Name Value Notes 

Name combo box DID_NAME 301 Drop-down list 

Style combo box DID_STYLE 302 Drop-down list 

Display check box DID_DISPLAY_FILTER 303 Auto check box 

Printer check box DID_PRINTER_ FILTER 304 Auto check box 

Size combo box DID_SIZE 305 Drop-down 

Sample text string DID_SAMPLE 306 

Outline check box DID_OUTLINE 307 Auto check box 
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Underscore check DID_UNDERSCORE 308 Auto check box 
box 
Strikeout check box DID STRIKEOUT 309 Auto check box 
Help push button DID_HELP_BUTTON 310 Help style, no 
pointer focus 
Apply push button DID_APPLY_BUTTON _ 311 
Reset push button DID_ RESET BUTTON § 312 
Name text string DID_NAME_PREFTX 313 
Style text string DID_STYLE_PREFTX 314 
Size text string DID_SIZE PREFIX S15 
Sample group box DID_SAMPLE_ 316 
GROUPBOX 
Emphasis group box DID_EMPHASIS_ 317 
GROUPBOX 
ISO support text DID_FONT_ISO_ 318 
string SUPPORT 
ISO nonsupport text DID_FONT_ISO_ 319 
string UNTESTED 
OK push button DID_OK BUTTON 1 Default style 
Cancel pushbutton DID_CANCEL_ 2 
BUTTON 


If you add controls to a standard dialog, you must assign them 
identifiers greater than 4095. To respond to user action on the new 
controls, you must subclass the standard dialog by writing a dialog pro- 
cedure and calling WinDefFileDlgProc or WinDefFontDlgProc for un- 
processed messages. The built-in dialog function stores a pointer to 
the FILEDLG or FONTDLG structure at index zero in the dialog’s win- 
dow data structure. The custom dialog procedure can call Win- 
QueryWindowULong (pg 296) with index QWL_USER (value zero) to 
obtain this pointer, if required. 
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Standard Dialog Functions 





WinDefFileDlgProc provides default processing for the standard file 
dialog (pg 207). 

WinDefFontDlgProc provides default processing for the standard font 
dialog (pg 208). 

WinFileDlg displays a standard file dialog (pg 210). 

WinFontDlg displays a standard font dialog (pg 215). 
WinFreeFileDlgList frees storage allocated by the standard file dialog 


(pg 225). 





@ WinDefFileDlgProc 


Provides default processing for the standard file dialog. 


SYNTAX 


MRESULT WinDefFileDlgProc (HWND hwnd, ULONG msg, 
MPARAM mp1, MPARAM mp2) 


PARAMETERS 

hwnd - input 

The handle of the standard file dialog window. 
msg - input 

The message identifier. 

mpI - input 

The first message parameter. 

mp2 - input 

The second message parameter. 


RETURNS 


The message result. 


OTHER INFO 
Include file: pmstddlg.h Define: INCL_WINSTDDLGS 


SEE ALSO 
WinFileDlg -210 


208 OS/2 WARP Presentation Manager API 


NOTES 


To change the behavior and appearance of the standard file dialog, 
you can subclass the built-in file dialog procedure by writing your own 
dialog procedure, and calling this function for unprocessed messages. 
You must specify the address of your dialog procedure in the fildlg.pfn- 
DigProc field in WinFileDlg. 

You can also use this technique to intercept messages. The follow- 
ing custom file dialog procedure intercepts the WM_INITDLG message 
and changes the font used in the dialog: 


MRESULT EXPENTRY CustomFileDlgProc ( HWND hwnd, ULONG msg 
, MPARAM mpl, MPARAM mp2 ) 


As 


Switch ( msg ) 
{ 
case WM_INITDLG: 
{ 
char *psz = “10.Times New Roman”; 
BOOL fSuccess = WinSetPresParam ( hwnd, PP_FONTNAMESIZE 
, Strlen (ps2), psa }; 
pmassert ( f£Success, hab ); 
} 
break; 
} 
return WinDefFileDlgProc ( hwnd, msg, mpl, mp2 ); 


wre 





® WinDefFontDligProc 


Provides default processing for the standard font dialog. 


SYNTAX 


MRESULT WinDefFontDlgProc (HWND hwnd, ULONG msg, 
MPARAM mp1, MPARAM mp2) 


PARAMETERS 

hwnd - input 

The handle of the standard font dialog window. 
msg - input 

The message identifier. 
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mpI - input 

The first message parameter. 
mp2 - input 

The second message parameter. 


RETURNS 


The message result. 


OTHER INFO 
Include file: pmstddlg.h Define: INCL_WINSTDDLGS 


SEE ALSO 
WinFontDlg -215 


NOTES 


To change the behavior and appearance of the standard font dialog, 
you can subclass the built-in file dialog procedure by writing your own 
dialog procedure, and calling this function for unprocessed messages. 
You must specify the address of your dialog procedure in the fonidlg.pfn- 
DigProc field in WinFontDlg. 

You can also use this technique to intercept messages. The follow- 
ing custom font dialog procedure intercepts the WM_INITDLG mes- 
sage and changes the font used in the dialog itself: 


MRESULT EXPENTRY CustomFontDlgProc ( HWND hwnd, ULONG msg 
, MPARAM mpl, MPARAM mp2 ) 


Switch ( msg ) 
{ 
case WM_INITDLG: 
i 
char *psz = “10.Times New Roman”; 
BOOL fSuccess = WinSetPresParam ( hwnd, PP_FONTNAMESIZE 
, strlen (psz), psz ); 
pmassert ( fSuccess, hab ); 
. 
break; 
} 
return WinDefFontDlgProc ( hwnd, msg, mpl, mp2 ); 
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@ WinFileDlg 


Displays a standard file dialog. 


SYNTAX 

HWND WinFileDig (HWND hwndParent, HWND hwndOwner, 
PFILEDLG pfildig) 

PARAMETERS 


hwndParent - input 

The handle of the window that will act as the dialog’s parent. PM will 
clip the dialog to this window’s boundaries. Pass HWND_DESKTOP for 
the dialog to be clipped to the desktop, or pass HWND_OBJECT to cre- 
ate the dialog invisibly. 

hwndOuwner - input 

The handle of the window that will act as the dialog’s owner. PM will 
disable the owner from from receiving user input. Note: By default, the 
dialog is modal (disables its owner), but if you specify the F-DS_MODE- 
LESS flag in the fildig.fl field, then the file dialog will be modeless and 
will not disable its owner. If you make the dialog modeless, PM will not 
let the dialog “go behind” its owner in the stack of windows. You can 
also pass NULLHANDLE for a modeless dialog so it has no owner. 
pfildlg - input/output 

Pass the address of a FILEDLG structure. The dialog reads some of the 
fields of the structure on input and writes to some fields before re- 
turning: 


typedef struct _FILEDLG /* fildlg */ 
{ 


ULONG ebsize; 
ULONG a 

ULONG ulUser; 

LONG lReturn; 
LONG LISRC} 

PSZ pszTitle; 
PSZ pszOKButton; 
PFNWP pfnDlgProc; 
PSZ pszitype; 


PAPSZ papszITypeList; 
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PSZ psziDrive; 

PAPSZ papsziDriveList; 
HMODULE hMod; 

CHAR szFullFile{CCHMAXPATH] ; 
PAPSZ papszFQFilename; 

ULONG ulFQFCount ; 

USHORT usDlgId; 


SHORT > a 

SHORT Vi 

SHORT SEAType; 
} FILEDLG; 


cbSize Input field. Initialize this field to the length of the structure, 
in bytes. 

fl Input field. A combination of the following flags, but you must 
specify either FDS_OPEN_DIALOG or FDS_SAVEAS_ DIALOG (but 
not both): 

FDS_APPLYBUTTON Include a pushbutton labeled Apply. Gen- 
erally used in modeless dialogs. When the user presses this but- 
ton, the dialog doesn’t dismiss, but posts WM_COMMAWND to its 
owner, passing SHORTIFROMMP(mp1) set to the dialog’s identi- 
fier and SHORTIFROMMP(mp2) set to CMDSRC_FILEDLG (value 
5). See the note below on the modeless dialogs. 

FDS_CENTER Center the dialog on its owner. 

FDS_CUSTOM_ Use a custom dialog template. You must fill in the 
hmod and usDigID fields to indicate the dialog resource location. 

FDS_ENABLEFILELB For FDS_SAVEAS_DIALOGs only. Without 
this flag, the dialog disables the file list box so the user cannot se- 
lect files from the list. 

FDS_FILTERUNION Without this flag, when the dialog fills the 
file list box, it only lists files that match both the file name string 
filter (szFullFile field) and the extended attribute type string filters 
(pszlType and papszlTypeList fields). With this flag, the dialog lists 
files that match either filter. 

FDS_HELPBUTTON Includes a Help pushbutton. When the user 
selects this button, the dialog passes WM_HELP to the owner 
window. 

FDS _INCLUDE_EAS Without this flag, the dialog doesn’t query 
extended attributes for files as it fills the file list box, unless you 
also specify an extended attribute filter. 
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FDS_MODELESS Without this flag, the dialog is modal, disables 
its owner, and doesn’t return until the user dismisses the dialog 
With this flag, WinFileDlg returns immediately with the modeless 
dialog’s window handle. See the FDS_APPLY flag and the discus- 
sion on modeless dialogs in the Notes section. Also note that be- 
cause this function returns immediately, but the dialog function 
uses the file-dialog structure, you must allocate the structure so 
that it’s not freed until the dialog terminates. Be especially care- 
ful allocating the structure as a local variable on the stack—it’s 
better to allocate the structure as static. 

FDS_MULTIPLESEL Without this flag, the file listbox allows one 
selection at a time. With this flag, the user can select more than 
one file. 

FDS_OPEN_DIALOG Creates a File-Open dialog. Mutually exclu- 
sive with FDS_FILESAVEAS_DIALOG. 

FDS_PRELOAD VOLINFO Without this flag, the dialog doesn’t 
query the volume information for the disk volumes listed in the 
drive list box. With this flag, it takes longer for the dialog to ini- 
tialize, but it’s faster when the user changes the drive. 

FDS_SAVEAS DIALOG Creates a File-Save-As dialog. Mutually ex- 
clusive with FDS_FILE_OPEN_DIALOG. 

ulUser This is an input/output field. The dialog ignores this field, 
but a custom dialog procedure can use it for any purpose. See the 
note on modeless dialogs for a sample application. 

IReturn Output field. The dialog fills in this field with the identifier 
of the pushbutton that the user pressed to dismiss the dialog. Unless 
you add custom pushbuttons, this identifier will be DID_OK or 
DID_CANCEL. 

ISRC Output field. The dialog fills in this field with one of the fol- 
lowing system error codes: 


0 - FDS_SUCCESSFUL 

1 - FDS_ERR_DEALLOCATE_MEMORY 

2-FDS_ERR_ FILTER _TRUNC 

3 - FDS_ERR_INVALID_DIALOG 

4-FDS_ERR_INVALID_DRIVE 

5 - FDS_ERR_ INVALID _FILTER 

6-FDS_ERR_ INVALID _PATHFILE 

7 - FDS_ERR_OUT_OF_MEMORY 

8 - FDS_ERR_PATH_TOO_LONG 

9-FDS_ERR_TOO_MANY_FILE_ TYPES 
10 - FDS_ERR_INVALID_VERSION 
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11 - FDS_ERR_INVALID_ CUSTOM_HANDLE 
12-FDS_ERR_ DIALOG_LOAD_ERROR 
13 - FDS_ERR_DRIVE_ERROR 


pszTitle Input field. If you set this to NULL, the dialog adopts a stan- 
dard title. Otherwise, set it to the title string desired. 

pszOKButton Input field. If you set this to NULL, the OK button dis- 
plays OK. Otherwise, set it to the button text desired. 

pfnDigProc Input field. Set this to NULL unless you have written a 
dialog subclass procedure, in which case, set it to the subclass pro- 
cedure’s address. 

pszIType Input field. If you set this to NULL, the dialog applies no 
extended attribute filtering to the File list box (See the papszl- 
TypeList and szFullFile fields). Otherwise, set to the single . TYPE ex- 
tended attribute for filtering. 

papszITypeList Input field. If you set this to NULL, the dialog ap- 
plies no extended attribute filtering to the File list box (See the 
pszlType and szFullFile fields). Otherwise, pass a pointer to an array 
of pointers to extended attribute .7YPE strings. The last pointer 
should be NULL to terminate the array. The dialog will display the 
. TYPE strings in the Type combo box. 

pszIDrive Input field. If you set this to NULL, the dialog initially se- 
lects the current drive in the Drives combo box. Otherwise, set this 
to the drive string to be initially selected (such as D:). 

papszIDrivelistInput field. If you set this to NULL, the dialog displays 
all available drives in the Drives combo box. To limit the drives dis- 
played, pass a pointer to an array of pointers to drive strings (such as 
D:). The last pointer should be NULL to terminate the array. 

hmod_ Input field. If you specify /DS_CUSTOM in the fl field, set this 
to the module handle of the dynamic link library containing the di- 
alog resource, or NULLHANDLE if the resource is bound to the 
current executable. The dialog ignores this field unless you specify 
FDS_CUSTOM. 

szFullFile Input and output field. This string should contain CCH- 
MAXPATH (defined in BSEDOS.H) characters. On input, set to a 
string that the dialog uses to filter file names in the Files list box. You 
can specify a file filter with wild cards, such as *.ICO. See also the 
pszlType and papszlTypeList fields. If you set this to a NULL string 
(first character is \'0’), the dialog performs no file name filtering. 
On output, the dialog returns the string for any selected file here. If 
you specify the FDS_MULTIPLESEL flag and the user selects multi- 
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ple files, the first file’s string is returned (see the papsziQFilename 
field for all of the selected files). 

papszFQFilename Output field. Ignored unless you specify the 
FDS_MULTIPLESEL flag. The dialog returns a pointer to an array of 
file name string pointers. The last pointer in the array will be NULL. 
Since the dialog allocates the storage for this array, you must call 
WinFreeFileDlgList to free the storage when you are finished with it. 

wFOQFCount Output field. The dialog fills in this field with the num- 
ber of selected file names. 

usDlgId Input field. If you specify FDS_CUSTOM in the fl field, set 
this to the resource identifier of the custom dialog. The dialog ig- 
nores this field unless you specify K-DS_CUSTOM. 

x Input and output field. The x-coordinate of the dialog relative to 
its parent’s lower left, in pixels. The dialog ignores this field if you 
specify FDS_CENTER in the flags. The dialog updates this field with 
the dialog’s final position. 

y Inputand output field. The y-coordinate of the dialog relative to its 
parent’s lower left, in pixels. The dialog ignores this field if you spec- 
ify FDS_CENTER in the flags. The dialog updates this field with the 
dialog’s final position. 

sEAType Output field. Only applies to Save-As dialogs. The dialog 
fills this field with an index into the papszITypeList array to indicate 
the selected file’s .7YPE extended attribute. 


RETURNS 


If you specify FDS_MODELESS in the flags, this function returns the 
modeless dialog handle, or NULLHANDLE if an error occurred. 
If you do not specify FDS_MODELESS in the flags, this function re- 
turns TRUE if the dialog was displayed successfully, FALSE otherwise. 
In either case, see the fildig. Return field for an error code. 


OTHER INFO 
Include file: pmstddlg.h Define: INCL_WINSTDDLGS 


SEE ALSO 


WinDefFileDlg -207, WinFreeFileDlgList -225, 
WinQueryWindowULong -296, WinQueryDlgItemText -194 


NOTES 


If you create a modeless dialog, you can write a custom dialog proce- 
dure and use the ulReturn field to return a pointer to the selected file 
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name. In the custom dialog procedure, intercept the WM_COMMAND 
message with the DID_APPLY_PB identifier. Query the text from the 
DID_FILENAME_ED entry field and store in a statically defined string. 
Then query a pointer to the fildig structure from the QWL_USER field 
in the dialog’s window words and store the string’s pointer in the ulUser 
field. Then, in the main window procedure, when it receives the 
WM_COMMAND message from the modeless dialog, it can examine 
the ulUser field for the selected file name string. 


EXAMPLE 


The following fragment from a client window procedure displays a 
modal single-selection file open dialog and opens any selected file: 


FILEDLG fildig: // file dialog structure 
BOOL fSuccess; // return from API 
// initialize the file dialog structure 
memset ( &fildlg, 0, sizeof (fildlg) ); 
fildlg.cbSizge = sizeof { fildlg ); 
fildlg.fl = FDS_OPEN_DIALOG | 
FDS _CENTER; 
// display the modal file dialog 
fSuccess = (BOOL)WinFileDlg ( HWND_DESKTOP 
, WinQueryWindow ( hwnd, QW_PARENT ) 
, &@£ildlg }; 
// if the user OKed the dialog, open the file 
Lf { Fildico.lRéturn == DID_OK } 
{ 
FILE *£; 
{f = fopen { fildig.szFuliFile;, *“r" }: 





WinFontDlg 


Displays a standard font dialog. 
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SYNTAX 

HWND WinFontDlg (HWND hwndParent, HWND hwndOwner, 
PFONTDLG p/nidig) 

PARAMETERS 


hwndParent - input 

The handle of the window that will act as the dialog’s parent. PM will 
clip the dialog to this window’s boundaries. Pass HWND_DESKT OP for 
the dialog to be clipped to the desktop, or pass HWND_OBJECT to cre- 
ate the dialog invisibly. 

hwndOwner - input 

The handle of the window that will act as the dialog’s owner. PM will 
disable the owner from receiving user input. Note: By default, the dia- 
log is modal (disables its owner), but if you specify the ADS_MODELESS 
flag in the /fntdilg.fl field, then the file dialog will be modeless and will 
not disable its owner. If you make the dialog modeless, PM will not let 
the dialog “go behind” its owner in the stack of windows. You can also 
pass NULLHANDLE for a modeless dialog so it has no owner. 

pfntdlg - input/output 

Pass the address of a FONTDLG structure. The dialog reads some of the 
fields of the structure on input and writes to some fields before re- 
turning: 


typedef struct _FONTDLG /*® fotdlg */ 
{ 
ULONG cbSize; 


HPS hpsScreen; 

HPS hpsPrinter; 
PSZ pszTitle; 

PSZ pszPreview; 
PSZ pszPtSizeList; 


PFNWP pfnDlgProc; 
PSZ pszFamilyname; 
FIXED fxPointSize; 
ULONG E1% 

ULONG flFlags; 

ULONG flType; 

ULONG flTypeMask; 
ULONG flStyle; 

ULONG flStyleMask; 
LONG clrFore; 


Standard Dialogs 217 


LONG clrBack; 

ULONG ulUser; 

LONG lReturn; 

LONG LERC; 

LONG lEmHeight; 

LONG 1XHeight; 

LONG lExternalLeading; 
HMODU 


FATTR. CAttrs; 
SHORT sNominalPointSize; 
USHORT usWeight; 
USHORT usWidth; 
SHORT x 
SHORT Vv? 
USHORT usDlgId; 
USHORT usFamilyBufLen; 
USHORT usReserved; 
} FONTDLG; 


cbSize Input field. Initialize this field to the length of the structure, 
in bytes. 

hpsScreen Input field. If you set this to NULLHANDLE, the dialog 
doesn’t display any screen fonts and disables the Display check box. 
Otherwise, set to a presentation space handle associated with a win- 
dow device context. 

hpsPrinter Input field. If you set this to NULLHANDLE, the dialog 
doesn’t display any printer fonts and disables the Printer check box. 
Otherwise, set to a presentation space handle associated with a 
printer device context. 

pszTitle Input field. Ifyou set this to NULL, the dialog displays the ti- 
tle: Font. Otherwise, set a text string for the dialog title. 

pszPreview Input field. If you set this to NULL, the dialog displays 
the preview string: abcdABCD. Otherwise, set to the preview string 
desired. 

pszPtSizeList Input field. If you set this to NULL, displays 8, 10, 12, 
14, 18, and 24 point sizes in the Size combo box. Otherwise, pass a 
string containing a list of point sizes, separated by spaces. 

pfnDigProc Input field. Set this to NULL unless you have written a 
dialog subclass procedure, in which case, set the the subclass proce- 
dure’s address. 

pszFamilyName Input and output field. On input, the dialog uses 
this pointer to find a string that it uses to choose the initial font in 
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the Name field. On output, the dialog uses this pointer to store the 
name of the font that the user selected. You must allocate enough 
storage for the string and pass its address here. The string should 
contain FACESIZE characters (defined in OS2DEF.H), and you 
should initialize the usFamilyBufLen field to this string’s size. 


fxPointSize Input and output field. On input, pass the point size you 


want the dialog to show initially, or zero to default. Pass this real 
number value in FIXED format using the MAKEFIXED macro de- 
fined in PMGPI.H (for example, MAKEFIXED (12,0) creates a fixed 
number for 12 points). On output, the dialog fills in the point size 
selected here. You can use the FIXEDINT macro to extract the inte- 
ger portion, and FIXEDFRAC to extract the fractional portion. 


fl Input field. A combination of the following flags: 


FNTS_APPLYBUTTON Include a push button labeled “Apply”. 
Generally used in modeless dialogs. When the user presses this but- 
ton, dialog doesn’t dismiss, but posts WM_COMMAND to its owner, 
passing SHORTLFROMMP(mp1) set to the dialog’s identifier and 
SHORTIFROMMP(mp2) set to CMDSRC_FONTDLG (value 4). 

FNTS_BITMAPONLY The dialog should display only raster (bit- 
map) fonts. Mutually exclusive with FNTS_VECTORONLY. 

FNTS_CENTER Center the dialog on its owner. 

FNTS_CUSTOM Use a custom dialog template. You must fill in 
the hmod and usDigID fields to indicate the dialog resource loca- 
tion. 

FNTS_FIXEDWIDTHONLY The dialog should display only mono- 
spaced fonts. Mutually exclusive with FNTS_PROPORTIONAL- 
ONLY. 

FNTS_HELPBUTTON Includes a Help pushbutton. When the 
user selects this button, the dialog passes WM_HELP to the owner 
window. 

FNTS_INITFROMFATTRS The dialog should preselect a font 
based on the embedded FATTRS structure. If you don’t use this 
flag, the dialog ignores the FATTRS on input and preselects a font 
based on other fields. 

FNTS_MODELESS Without this flag, the dialog is modal, disables 
its owner, and doesn’t return until the user dismisses the dialog. 
With this flag, WinFontDlg returns immediately with the modeless 
dialog’s window handle. See the FNTS_APPLY flag. Also note that 
because this function returns immediately, but the dialog function 
uses the font-dialog structure, you must allocate the structure so 
that it’s not freed until the dialog terminates. Be especially careful 
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allocating the structure as a local variable on the stack—it’s better 
to allocate the structure as static. 

FNTS_NOSYNTHESIZEDFONTS The dialog should not show 
synthesized bold and italic versions of raster fonts that do not 
have separate bold and italic definitions. 

FNTS_QOWNERDRAWPREVIEW The dialog should pass WM_ 
DRAWITEM messages to the owner window so it can draw the pre- 
view area. This feature is useful if you wish to create a custom dia- 
log resource that has additional font attributes the user can se- 
lect, and you want the preview window to reflect the custom 
attributes. ‘The dialog passes the preview window identifier in mp1 
and a pointer to an OWNERITEM structure in mp2. This structure 
contains an hwnd field, an hps field, and an rclltem field for the 
preview window. The owner should return TRUE on this message 
if it drew the preview window, FALSE if it wants the dialog to draw 
the window. 

FNTS_PROPORTIONALONLY The dialog should display only 
proportionally spaced fonts. Mutually exclusive with FNTS_ 
FIXEDWIDTHONLY. 

FNTS_RESETBUTTON Include a pushbutton labeled Reset. 
When the user presses this button, the dialog doesn’t dismiss, but 
instead resets to its initial state. 

FNTS_VECTORONLY The dialog should display only outline 
(vector) fonts. Mutually exclusive with FNTS_BITMAPONLY. 

flFlags Input and output field. A combination of the following flags: 

FNTF_NOVIEWPRINTERFONTS Examined on input, but only 
applies if you pass both screen and printer presentation spaces in 
hpsScreen and hpsPrinier. Indicates that the dialog should initially 
display only screen fonts. ‘The user can see printer fonts by select- 
ing the Printer check box. 

FNTF_NOVIEWSCREENFONTS Examined on input, but only 
applies if you pass both screen and printer presentation spaces in 
hpsScreen and hpsPrinter. Indicates that the dialog should initially 
display only printer fonts. The user can see screen fonts by select- 
ing the Display check box. 

FNTF_PRINTERFONTSELECTED Output flag that indicates 
that the user selected a printer font. The program should display 
the closest matching screen font when writing to its window. 

FNTF_SCREENFONTSELECTED Output flag that indicates that 
the user selected a display font. The program should display the 
closest matching printer font when printing. 
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flType Input and output field. A combination of the following flags 
that you can use as the flOptions field in the FACENAMEDESC struc- 
ture of GpiQueryFaceString. Note that the dialog may also return 
an italic indication in the szFacename field of the embedded FATTRS 
structure. 

FTYPE_ITALIC Request an italic font. 

FTYPE ITALIC DONT CARE Matcha font whether italic or not. 

FTYPE_OBLIQUE Request an oblique font. 

FTYPE_OBLIQUE_DONT_CARE Match a font whether oblique 
or not. 

FTYPE_ROUNDED Request a rounded font. 

FTYPE ROUNDED DONT CARE Matcha font whether rounded 
or not. 

flTypeMask Output field. If you specify FNTS_OWNERDRAWPRE- 
VIEW, this field indicates which /lType bits the user changed. 

flStyle Input and output field. A combination of font style flags. 
These flags are also found in the /fsSelectzon field of the embedded 
FATTRS structure. 

FATTR_SEL_ITALIC Request an italic font. The font dialog 
doesn’t appear to use this flag, but instead uses the equivalent flag 
in the flType field. 

FATTR_SEL_UNDERSCORE Request an underscored font. 

FATTR_SEL_OUTLINE Request a hollow font. 

FATTR_SEL_STRIKEOUT Request a font with a line drawn 
through the characters. 

FATTR_SEL_BOLD Request a bold font. The font dialog doesn’t 
appear to use this flag, but instead uses the usWeghi field to re- 
quest a bold font. 

flStyleMask Output field. If you specify FNTS_OWNERDRAWPRE- 
VIEW, this field indicates which /lStyle bits the user changed. 

clrFore The font foreground color (used in preview window). 

clrBack The font background color (used in preview window). 

wlUser This is an input/output field. The dialog ignores this field, 
but a custom dialog procedure can use it for any purpose. 

IReturn Output field. The dialog fills in this field with the identifier 
of the pushbutton that the user pressed to dismiss the dialog. Unless 
you add custom pushbuttons, this identifier will be DID_OK or 
DID_CANCEL. 

ISRC Output field. The dialog fills in this field with one of the fol- 
lowing system error codes: 
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0 - FNTS_SUCCESSFUL 
3-FNTS_ERR_ INVALID _DIALOG 
4-FNTS_ERR_ ALLOC_SHARED_ MEM 
5 - FNTS_ERR_ INVALID _PARM 
7-FNTS_ERR_OUT_OF_MEMORY 
10- FNTS_ERR_ INVALID_VERSION 
12-FNTS_ERR_DIALOG_LOAD_ERROR 


IKmHeight Output field. The Em height of the selected font in world 
coordinates. 

IXHeight Output field. The X height of the selected font in world co- 
ordinates. 

IExternalLeading Output field. The external leading of the selected 
font in world coordinates. 

hmod Input field. If you specify KNTS_CUSTOM in the fl field, set 
this to the module handle of the dynamic link library containing the 
dialog resource, or NULLHANDLE if the resource is bound to the 
current executable. The dialog ignores this field unless you specify 
FNTS_CUSTOM. 

fattrs Output field, but also input if you specify FNTS_INITFROM- 
FATTRS in the fl field. This is an embedded structure that you can 
pass to GpiCreateLogFont upon return to make the selected font 
available for your program. See the Notes section for the FATTRS 
description. 

sNominalPointSize Output field. The point size of the selected font, 
times 10. 

usWeight Input and output field. A boldness value that you can pass 
as the usWeightClass field in the FACENAMEDESC structure to Gpi- 
QueryFaceString. One of the following values: 


FWEIGHT_DONT_CARE 
FWEIGHT_ULTRA_LIGHT 
FWEIGHT_EXTRA_LIGHT 
FWEIGHT_LIGHT 
FWEIGHT_SEMI_ LIGHT 
FWEIGHT_NORMAL 
FWEIGHT_SEMI_ BOLD 
FWEIGHT_ BOLD 
FWEIGHT_EXTRA_ BOLD 
FWEIGHT_ULTRA_BOLD 
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usWidth Input and output field. A width value that you can pass 
as the usWidthClass field in the FACENAMEDESC structure to 
GpiQueryFaceString. One of the following values: 


FWIDTH_DONT_CARE 
FWIDTH_ULTRA_ CONDENSED 
FWIDTH_EXTRA_CONDENSED 
FWIDTH_CONDENSED 
FWIDTH_SEMI_ CONDENSED 
FWIDTH._ NORMAL 
FWIDTH_SEMI_ EXPANDED 
FWIDTH_EXPANDED 
FWIDTH_EXTRA_ EXPANDED 
FWIDTH_ULTRA_ EXPANDED 


x Input and output field. The x-coordinate of the dialog relative to 
its parent’s lower left, in pixels. The dialog ignores this field if you 
specify FNTS_CENTERin the flags. The dialog updates this field with 
the dialog’s final position. 

y Inputand output field. The y-coordinate of the dialog relative to its 
parent’s lower left, in pixels. ‘The dialog ignores this field if you spec- 
ify FNTS_CENTER in the flags. The dialog updates this field with the 
dialog’s final position. 

usDigId Input field. If you specify FNTS_CUSTOM in the fl field, set 
this to the resource identifier of the custom dialog. The dialog ig- 
nores this field unless you specify FNTS_CUSTOM. 

usFamilyBufLen Input field. Pass the number of bytes in the buffer 
pointed by pszFamilyName. 

usReserved Not used. 


RETURNS 


If you specify FNTS_MODELESS in the flags, this function returns the 
modeless dialog handle or NULLHANDLE if an error occurred. 

If you do not specify FNTS_MODELESS in the flags, this function 
returns TRUE if the dialog was displayed successfully, FALSE other- 
wise. 

In either case, see the /nidlg.lReturn field for an error code. 


OTHER INFO 
Include file: pmstddlg.h Define: INCL_WINSTDDLGS 


SEE ALSO 
WinDefFontDlg -208 


Standard Dialogs 220 


NOTES 


This dialog lets the user select a font which the program can then use 
to display or print text. PM supports two font technologies: raster 
(sometimes called bitmap) fonts and outline (sometimes called vec- 
tor) fonts. Raster fonts display faster, but outline fonts are device-inde- 
pendent and thus are better for programs that want the display and 
printed text to look the same. 

If the user selects a raster font, the program can use the returned 
FATTRS structure (described below) as an input to GpiCreateLog to 
load the font into the presentation space and then call GpiSetCharSet 
to make the font the current font. If the user selects an outline font, 
the program must also scale the font to the selected point size using 
GpiSetCharBox. You can tell if the user selected a raster or outline font 
by examining the /sFontUse field in the FATTRS structure. 


typedef struct _FATTRS j* fat */ 
{ 
USHORT usRecordLength; 
USHORT fsSelection; 
LONG 1Match; 
CHAR szFacename{FACESIZE] ; 
USHORT idRegistry; 
USHORT usCodePage; 
LONG 1MaxBaselineExt; 
LONG lAveCharwidth; 
USHORT fsType; 
USHORT fsFontUse; 
} FATTRS; 


usRecordLength ‘The size of the structure in bytes. 

fsSelection A combination of the following flags: 
FATTR SEL BOLD Bold font. 
FATTR_SEL_ITALIC Italic font. 
FATTR_SEL_ OUTLINE Hollow characters. 
FATTR_SEL_STRIKEOUT Characters with a line through them. 
FATTR_ SEL UNDERSCORE Underlined characters. 

IMatch A handle assigned to the font by the system. This handle is 
unique for a given face name. 

szFaceName ‘The font’s face name string. 

idRegistry The font’s registry number or zero. 

usCodePage The font’s code page. 
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IMaxBaselineExt For raster fonts, the maximum baseline extension, 
which measures the font’s height in world coordinates. 
JAveCharWidth For raster fonts, the width of an average character in 
world coordinates. 
fsType A combination of the following flags: 
FATTR_TYPE_KERNING Set if the font supports kerning. 
FATTR_TYPE_MBCS Set if the font is a multiple-byte charac- 
ter set. 
FATTR_TYPE_DBCS Set if the font is a double-byte character set. 
FATTR_TYPE_ANTIALIASED  Setif the font supports anti-aliasing 
on hardware that also provides such support. 
fsFontUse A combination of the following flags: 
FATTR FONTUSE NOMIX Set if the characters in this font can 
be mixed with graphics. 
FATTR FONTUSE OUTLINE Set if the font is an outline font 
instead of a vector font. 
FATTR_FONTUSE_TRANSFORMABLE Set if the outline font 
supports scaling, displacement, shearing, and rotation. 


EXAMPLE 


The following fragment from a client window procedure displays a 
modal font selection dialog and sets the selected font into the presen- 
tation space. This program only supports raster screen fonts. It as- 
sumes that the window uses a micro presentation space whose handle 
is stored in a static variable: 


CHAR szFamilyname{FACESIZE] ; // font name 
FONTDLG fntdlg; // Eont dialog strict 
BOOL FSuccess; // return from API 


// £i1ll in the required fields in 
// the font dialog structure 
memset ( &fntdlg, 0, sizeof ( FONTDLG ) ); 
fntdlg.cbSize = sizeof ( FONTDLG ); 
fntdlg.hpsScreen = hps; 
fntdlg.pszFamilyname = szFamilyname; 
fntdlg.fl1 = FNTS_CENTER | FNTS_BITMAPONLY; 
fntdlg.usFamilyBufLen = sizeof (szFamilyname) ; 
// display a modal font-selection dialog 
fSuccess = (BOOL)WinFontDlg ( HWND_DESKTOP 
, WinQueryWindow ( hwnd, QW_PARENT ) 
, Sincdlg ); 
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Lf { £Success == FALSE ) 
WinMessageBox ( HWND_DESKTOP, WinQueryWindow ( hwnd, QW_PARENT ) 
, “Bad return from WinFontDlg” 
;  BEror” 
, O, MB_OK | MB MOVEABLE) ; 
if { fntdlg.lReturn == DID OK ) 
{ 
// delete the previous logical font 
GpiDeleteSetId ( hps, 1 ); 
// create a new logical font and 
// make it the current font 
fSuccess = GpiCreateLogFont ( hps, NULL, 1, &fntdlg.fAttrs ); 
fSuccess = GpiSetCharSet ( hps, 1 ); 
// force a repaint 


WininvalidateRect ( hwnd, NULL, TRUE ); 





WinFreeFileDigList 


Frees storage allocated by the standard file dialog. 


SYNTAX 
BOOL WinFreeFileDlgList (PAPSZ papszFQFilename) 


PARAMETERS 
papszFQFilename - input 
Pass the the pointer to the array of pointers allocated by WinFileDlg. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmstddlg.h Define: INCL_WINSTDDLGS 


SEE ALSO 
WinFileDlg -210 


NOTES 
See the FDS_MULITPLESEL flag in WinFileDlg. 


ell 
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Presentation Manager resource is a block of read-only data, such 

as an icon, font, or dialog template. The usual way to define a re- 
source is to write a resource script in a resource file which you then 
compile with the resource compiler (it creates a .RES file from a .RC 
file). You can then bind the compiled resources to an executable file 
or to a dynamic link library. The following resources are currently sup- 
ported: 


Accelerator tables An accelerator table translates keystroke mes- 
sages, typically to menu commands. 

Bitmaps_ A bitmap is a set of binary data that represents an image on 
a raster device. This resource is not covered in this chapter, but you 
can load a bitmap resource with GpiLoadBitmap and display it with 
WinDrawBitmap (pg 115) or GpiBitBlt. 

Dialogs A program can define a dialog template resource and load it 
with WinLoadDlg (pg 181) or WinDlgBox (pg 175), which are cov- 
ered in Chapter 9, Dialogs. 

Menus A program can define a menu template resource and load it 
with WinLoadMenu (pg 160). Covered in Chapter 8, Menus. 

Pointers andicons An icon is set of two bitmaps that the system draws 
to represent a program, file, or object on the desktop. A pointer is 
the same as an icon except that it also specifies a hot spot pixel and 
thus can be used by the system for the mouse pointer. The 
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WinDrawPointer function is covered in Chapter 6, Window Drawing 
Functions. 
Messages and Strings A message or string is a null-terminated set of 
characters. 
A program can also load resources into memory using kernel 
functions, such as DosGetResource. 
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WinCopyAccelTable copies an accelerator table to memory (pg 228). 
WinCreateAccelTable creates a new accelerator table from memory 
(pg 230). 

WinCreatePointer creates a monochrome pointer from a bitmap 
(pg 232). 

WinCreatePointerIndirect creates a color or monochrome pointer 
from bitmaps (pg 233). 

WinDeleteLibrary frees a dynamic link library for a process (pg 235). 
WinDeleteProcedure frees a dynamically loaded function address for a 
process (pg 236). 

WinDestroyAccelTable deletes an accelerator table (pg 236). 
WinDestroyPointer deletes a pointer or icon (pg 237). 
WinFreeFileIcon frees an icon handle returned by WinLoadFileIcon 
(pg 238). 

WinLoadAccelTable loads an accelerator table from a resource (pg 238). 
WinLoadFilelIcon retrieves an icon handle from an executable or data 
file (pg 239). 

WinLoadLibrary loads a dynamic link library for a process (pg 241). 
WinLoadMessage loads a message from a resource (pg 241). 
WinLoadPointer loads a pointer from a resource (pg 243). 
WinLoadProcedure retrieves a dynamically loaded function address 
(pg 244). 

WinLoadString loads a string from a resource (pg 245). 
WinLockPointerUpdate locks the system mouse pointer shape for a 
specific time interval (pg 246). 

WinQueryAccelTable retrieves an accelerator table handle from a 
frame window or the handle of the system accelerator table (pg 247). 
WinQueryPointer queries the current system pointer’s handle (pg 248). 
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WinQueryPointerInfo retrieves information about a pointer or icon 
(pg 249). 

WinQueryPointerPos retrieves the current mouse pointer’s position 
(pg 250). 

WinSetAccelTable attaches an accelerator table to a frame window or 
sets the system accelerator table (pg 251). 

WinSetFileIcon assigns an icon to an executable or data file (pg 253). 
WinSetPointer sets the current mouse pointer for the system (pg 254). 
WinSetPointerOwner lets a pointer be shared between processes 
(pg 255). 

WinSetPointerPos changes the current mouse pointer’s position 
(pg 256). 

WinShowPointer increments or decrements the system mouse 
pointer’s hide count (pg 257). 

WinTranslateAccel translates keystroke messages (pg 258). 





@ WinCopyAccelTable 


Copies an accelerator table to memory. 


SYNTAX 


ULONG WinCopyAccelTable (HACCEL haccel, PACCELTABLE 
paccel, ULONG cb) 


PARAMETERS 


haccel - input 

The handle of an existing accelerator table. 

paccel - input/output 

If you pass NULL, this function doesn’t copy the table, but the return 
value indicates the amount of memory required to hold the table. 
Otherwise, pass the address of an ACCELTABLE structure where this 
function will store the accelerator table: 


typedef struct _ACCELTABLE /* acct */ 
{ 

USHORT cAccel; 

USHORT codepage; 

ACCEL aaccel[1]; 
} ACCELTABLE; 
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cAccel Number of accelerators in the table. 

codepage ‘The accelerator table’s code page. 

aaccel A list of cAccel number of structures, described in the fol- 
lowing. 


Each entry in this list is an ACCEL structure: 


typedef struct _ACCEL /* acc */ 
{ 

USHORT fs; 

USHORT key; 

USHORT cmd; 
} ACCEL; 


fs A combination of the following flags: 
AF ALT The Alt key must be down for translation. 
AF CHAR The key field is an ASCII value. 
AF_ CONTROL The Control key must be down for translation. 
AF HELP The accelerator generates the WM_HELP message. 
AF _LONEKEY The accelerator translates on modifier keys. 
AF SCANCODE The key field is a scan code. 
AF SHIFT The Shift key must be down for translation. 
AF SYSCOMMAND The accelerator generates a WM_SYSCOM- 

MAND message 

AF _VIRTUALKEY The key field is a virtual key code. 

key The keystroke value translated. Interpret this value based on the 
AF_CHAR, AF _SCANCODE, and AF_VIRTUALKEY codes as de- 
scribed above. 

cmd The identifier to which the keystroke is translated. This value is 
passed in the least-significant portion of the first message parameter 
in WM_COMMAND, WM_SYSCOMMAND, or WM_HELP. 


cb - input 
The size of the structure passed in the paccel argument. 


RETURNS 


Zero if the call failed, otherwise the size of the accelerator table in 
memory. 
Possible returns from WinGetLastError: 


OxlO1A - PMERR_ INVALID HACCEL 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINACCELERATORS 


SEE ALSO 


WinCreateAccelTable -230, WinQueryAccelTable -247, 
WinDestroyAccelTable -236, WinSetAccelTable -251, 
WinTranslateAccel -258 


NOTES 


This function lets you create a copy of an existing accelerator table in 
memory. You can then modify the memory to add, delete, or change 
an accelerator, and then create a new accelerator table with Win- 
CreateAccelTable and attach it to a frame window with WinSetAccel- 
Table or use with WinTranslateAccel. 





@ WinCreateAccelTable 





Creates a new accelerator table from memory. 


SYNTAX 
HACCEL WinCreateAccelTable (HAB hab, PACCELTABLE paccel) 


PARAMETERS 

hab - input 

Anchor block handle. 

paccel - input 

Pass the address of an ACCELTABLE structure that contains a list of 
ACCEL structures: 


typedef struct _ACCELTABLE /* acct */ 
i 

USHORT cAccel; 

USHORT codepage; 

ACCEL aaccel[1]; 
} ACCELTABLE; 


cAccel Number of accelerators in the table. 
codepage The accelerator table’s code page. 
aaccel A list of cAccel number of structures described in the following. 
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Each entry in this list is an ACCEL structure: 


typedef struct _ACCEL /* acc */ 
{ 

USHORT fs; 

USHORT key; 

USHORT cmd; 
} ACCEL; 


fs A combination of the following flags: 
AF _ALT The Alt key must be down for translation. 
AF CHAR The key field is an ASCII value. 
AF CONTROL The Control key must be down for translation. 
AF HELP The accelerator generates the WM_HELP message. 
AF LONEKEY § The accelerator translates on modifier keys. 
AF SCANCODE The key field is a scan code. 
AF SHIFT The Shift key must be down for translation. 
AF SYSCOMMAND The accelerator generates a WM_SYSCOM- 
MAND message 
AF _ VIRTUALKEY The hey field is a virtual key code. 
key The keystroke value translated. Set this value based on the AF_ 
CHAR, AF_SCANCODE, and AF_VIRTUALKEY codes as described. 
cmd ‘The identifier to which the keystroke is translated. The acceler- 
ator passes this value in the least-significant portion of the first mes- 
sage parameter in WM_COMMAND, WM_SYSCOMMAND, or WM_ 
HELP. 


RETURNS 


The accelerator table’s handle, or zero if an error occurred. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINACCELERATORS 


SEE ALSO 


WinLoadAccelTable -238, WinCopyAccelTable -228, 
WinQueryAccelTable -247, WinSetAccelTable -251, 
WinDestroyAccelTable -236, WinTranslateAccel -258 


NOTES 


This function creates an accelerator table that you can attach to a 
frame window with WinSetAccelTable or use with WinTranslateAccel. 
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You can also create an accelerator table from a resource using Win- 
LoadAccelTable. 

You should delete the accelerator table with WinDestroyAccel- 
Table when you are finished with it. 





@ WinCreatePointer 





Creates a monochrome pointer from a bitmap. 


SYNTAX 


HPOINTER WinCreatePointer (HWND hwndDesktop, HBITMAP hbm, 
BOOL /fSize, ULONG x, ULONG y) 


PARAMETERS 


hwndDesktop - input 

The desktop window’s handle (HWND_DESKTOP). 

hbm - input 

A handle to a bitmap that represents the pointer. The bitmap must 
have two distinct sections: the top half must be an “AND” mask, the 
bottom half an “XOR” mask. PM draws both masks when it draws the 
pointer. This technique allows transparent sections in the pointer. 
fSize - input 

Pass TRUE to create the pointer at system pointer size; FALSE to cre- 
ate the pointer at the system icon size. 

x - input 

The x-coordinate of the pointer’s hot spot from the pointer’s lower 
left. 

y - input 

The y coordinate of the pointer’s hot spot from the pointer’s lower 
left. 


RETURNS 


The pointer handle, or zero if an error occurred. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 
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SEE ALSO 


WinLoadPointer -243, WinCreatePointerIndirect -233, 
WinDestroyPointer -237, WinDrawPointer -121, WinSetPointer -254 


NOTES 


This function creates a pointer that you can draw with WinDraw- 
Pointer or set as the system mouse pointer with WinSetPointer. You 
should delete the pointer with WinDestroyPointer when you are fin- 
ished with it. 

This function creates only monochrome pointers. Use WinCreate- 
PointerIndirect to create color icons or pointers. 

If you set the pointer as the system pointer, PM passes mouse mes- 
sages to the window under the pointer’s hot spot. 

A program can also load a pointer from a resource using Win- 
LoadPointer. 

This function makes a copy of the provided bitmap so you can 
delete the bitmap after you create the pointer. 





WinCreatePointerlndirect 





Creates a color or monochrome pointer from bitmaps. 


SYNTAX 

HPOINTER WinCreatePointerIndirect (HWND hwndDesktop, 
PPOINTERINFO ppir.) 

PARAMETERS 


hwndDeshtop - input 

The desktop window’s handle (HWND_DESKTOP). 
pptri - input 

Pass the address of a POJINTERINFO structure: 


typedef struct _POINTERINFO /* ptri */ 
{ 

ULONG fPointer; 

LONG xHotspot; 

LONG yHotspot; 

HBITMAP hbmPointer; 

HBITMAP hbmColor; 
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HBITMAP hbmMiniPointer; 
HBITMAP hbmMiniColor; 
} POINTERINFO; 


fPointer Pass TRUE to create a pointer at system pointer size; FALSE 
to create an icon at the system icon size. 

xHotspot The x-coordinate of the pointer’s hot spot from the point- 
er’s lower left. 

yHotspot The y coordinate of the pointer’s hot spot from the point- 
er’s lower left. 

hbmPointer <A handle to a bitmap that represents the pointer or 
icon. The bitmap must have two distinct sections: the top half must 
be an “AND” mask, the bottom half an “XOR” mask. PM draws both 
masks when it draws the pointer or icon. This technique allows trans- 
parent sections. 

hbmColor A handle to a bitmap that contains the color informa- 
tion for the pointer or icon. This bitmap must be the same width as 
the bitmap passed in hbmPointer and one-half its height. In other 
words, the color bitmap must be the same size as the individual 
masks in the pointer bitmap. When PM draws the pointer or icon, it 
logically “ORS” the color bitmap with the result of drawing the 
“AND” and “OR” masks. 

hbmMiniPointer A handle for a small bitmap. See the previous hbm- 
Pointer discussion. 

hbmMiniColor A handle for a small bitmap. See the previous hbm- 
Color discussion. 


RETURNS 


The pointer or icon handle, or NULLHANDLE if an error occurred. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_ INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 


WinCreatePointer -232, WinLoadPointer -243, 
WinDestroyPointer -237, WinDrawPointer -121, WinSetPointer -254 
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NOTES 


This function creates a pointer or icon that you can draw with Win- 
DrawPointer or set as the system mouse pointer with WinSetPointer. 
You should delete the pointer or icon with WinDestroyPointer when 
you are finished with it. 

Icons and pointers are functionally the same except that PM de- 
fines different system sizes for them. In addition, PM uses the hot spot 
in a pointer to route mouse messages. 

This function copies the provided bitmaps so you can delete it af- 
ter you create the pointer or icon. 





WinDeleteLibrary 


Frees a dynamic link library for a process. 


SYNTAX 
BOOL WinDeleteLibrary (HAB hab, HLIB hlid) 


PARAMETERS 

hab - input 

Anchor block handle. 

hhb - input 

Handle of the library loaded by WinLoadLibrary. 
RETURNS 

TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINLOAD 


SEE ALSO 


WinLoadLibrary -241, WinLoadProcedure -244, 
WinDeleteProcedure -236 


NOTES 


This function is equivalent to DosFreeModule. 
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@® WinDeleteProcedure 





Frees a dynamically loaded function address for a process. 


SYNTAX 
BOOL WinDeleteProcedure (HAB hab, PFNWP pfnwp) 


PARAMETERS 

hab - input 

Anchor block handle. 
pfnwp - input 


The address of a window or dialog procedure returned by WinLoad- 
Procedure. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINLOAD 


SEE ALSO 


WinLoadLibrary -241, WinLoadProcedure -244 
WinDeleteLibrary -235 





@ WinDestroyAccelTable 


Deletes an accelerator table. 


SYNTAX 
BOOL WinDestroyAccelTable (HACCEL haccel) 


PARAMETERS 


haccel - input 
The handle of the accelerator table to destroy. 


RETURNS 
TRUE if successful, FALSE otherwise. 
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Possible returns from WinGetLastError: 


Ox1l01A - PMERR_ INVALID HACCEL 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINACCELERATORS 


SEE ALSO 
WinCreateAccelTable -230, WinLoadAccelTable -238 


NOTES 


You should destroy any accelerator table that you created with Win- 
CreateAccelTable. The system automatically destroys accelerator tables 
created with WinLoadAccelTable when the creating process exits. 





WinDestroyPointer 


Deletes a pointer or icon. 


SYNTAX 
BOOL WinDestroyPointer (HPOINTER hpir) 


PARAMETERS 
hptr - input 
The handle of the pointer or icon to destroy. 


RETURNS 


Possible returns from WinGetLastError: 


Ox101B - PMERR_ INVALID_HPTR 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 


WinCreatePointer -232, WinCreatePointerIndirect -233, 
WinQuerySysPointer -337 
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NOTES 


You should use this function to delete any pointers or icons created with 
WinCreatePointer, WinCreatePointerIndirect, or WinLoadPointer. Do 
not delete system pointers retreived with WinQuerySysPointer. 





@ WinFreeFilelcon 


Frees an icon handle returned by WinLoadFilelcon. 


SYNTAX 
BOOL WinFreeFilelcon (HPOINTER/pir) 


PARAMETERS 
hptr - input 
Icon handle returned by WinLoadFileIcon. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 
0x101B-PMERR INVALID HPTR 


OTHER INFO 
Include file: pmwp.h.h Define: INCL_WINWORKPLACE 


SEE ALSO 
WinLoadFilelIcon -239, WinSetFileIcon -253 





@ WinLoadAccelTable 





Loads an accelerator table from a resource. 


SYNTAX 


HACCEL WinLoadAccelTable (HAB hab, HMODULE hmod, 
ULONG 7d) 
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PARAMETERS 

hab - input 

Anchor block handle. 

hmod - input 

The handle of the dynamic link library containing the accelerator re- 
source. You can retrieve the DLL’s module handle with DosLoad- 
Module or DosQueryModuleHandle. If the resource is bound to the 
current executable, pass NULLHANDLE. 

id - input 

The accelerator table’s resource identifier. 


RETURNS 
The accelerator table handle, or NULLHANDLE if an error occurred. 
Possible returns from WinGetLastError: 


Ox100A - PMERR_ RESOURCE NOT_FOUND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINACCELERATORS 


SEE ALSO 


WinCreateAccelTable -230, WinCopyAccelTable -228, 
WinSetAccelTable -251, WinDestroyAccelTable -236, 
WinTranslateAccel -258 


NOTES 


This function creates an accelerator table from a resource that you can 
attach to a frame window with WinSetAccelTable or use with Win- 
‘TranslateAccel. Note that you can also create an accelerator table in 
memory using WinCreateAccelTable. 

When the process that loads the accelerator table terminates, PM 
automatically destroys the accelerator table. 





WinLoadFilelcon 





Retrieves an icon handle from an executable or data file. 


SYNTAX 
HPOINTER WinLoadFilelcon (PSZ pszFilename, BOOL fPrivate) 
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PARAMETERS 

pszFilename - input 

Pass the address of a string that contains the path name of an exe- 
cutable or data file. 

fPrivate - input 

Pass TRUE if you need your own private copy of the icon, FALSE to re- 
ceive a pointer to original icon. 


RETURNS 
The icon handle or NULLHANDLE if an error occurred. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWORKPLACE 


SEE ALSO 
WinSetFilelcon -253, WinFreeFileIcon -225 


NOTES 


This function returns an icon handle, given a file name. It will return 
an icon handle for any valid file name, using the algorithm shown 
below. 

If you pass TRUE for the fPrivate flag, you must free the icon with 
WinFreeFileIcon when you are finished. You should retrieve nonpri- 
vate handles if possible to reduce the number of resources allocated. 

This function searches for the first icon that matches one of the 
following criteria, using the following search order: 


1. ICON extended attribute attached to the file. 

2. If file name refers to an executable (.EXE, .COM, .CMD, .BAT) 
2a. ICO file with same file name prefix in the same directory. 
2b. Based on the .EXE’s type: 

Generic PM application icon. 

Generic Windows application icon. 
Generic OS/2 Windowed. 

Generic OS/2 full-screen application icon. 
Generic DOS application icon. 

3. If file name refers to a directory, generic directory icon. 

4. If file name refers to a data file: 
3a. Icon from any associated executable. 
3b. Generic data file icon. 
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® WinLoadLibrary 


Loads a dynamic link library for a process. 


SYNTAX 
HLIB WinLoadLibrary (HAB hab, PSZ pszPathname) 


PARAMETERS 

hab - input 

Anchor block handle. 

pszPathname - input 

Pass the address of a string containing the library’s path name. This 
function searches the LIBPATH configuration variable for a list of di- 
rectories that it searches if you do not pass a fully qualified path name. 


RETURNS 
The library’s module handle, or NULLHANDLE if an error occurred. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINLOAD 


SEE ALSO 


WinDeleteProcedure -236, WinLoadProcedure -244, 
WinDeleteLibrary -235 


NOTES 


This function is equivalent to DosLoadModule—it loads a dynamic 
link library (DLL) for a process. The returned HLIB is equivalent to an 
HMODULE. 

After loading the DLL, you can call WinLoadProcedure to retrieve 
the addresses of entry points in the DLL. 

When you are finished with the DLL, you should free for the call- 
ing process with WinDeleteLibrary. 





@ WinLoadMessage 


Loads a message from a resource. 
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SYNTAX 


LONG WinLoadMessage (HAB hab, HMODULE hmod, ULONG 
idString, LONG cch, PSZ psz) 


PARAMETERS 

hab - input 

Anchor block handle. 

hmod - input 

The handle of the dynamic link library containing the message table 
resource. You can retrieve the DLL’s module handle with DosLoad- 
Module or DosQueryModuleHandle. If the resource is bound to the 
current executable, pass NULLHANDLE. 

idString - input 

The identifier of a message string within the message table. 

cch - input 

The size of the output string. 

psz- output 

The output string where this function stores the message. 


RETURNS 
The returned message string’s length, or zero if an error occurred. 


Possible returns from WinGetLastError: 


Oxl00A - PMERR_ RESOURCE_NOT_FOUND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinLoadString -245 


NOTES 


This function loads a string from a message table defined in a resource 
file. For example: 


#define IDS_MESSAGE 16 

#define IDS_TITLE 17 

MESSAGETABLE 

{ 
IDS_MESSAGE "This is a test, this is only a test” 
IDS_TLITLE “Message Box Title” 
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A program could then load the messages and display them using: 


ULONG ch; // message length 
CHAR szTitle[255] >: // message box title 
CHAR szMsg[255]; // message box msg string 


cb = WinLoadMessage (hab, NULLHANDLE, IDS_TITLE 
, sizeof (szTitle), szTitle ); 

cb = WinLoadMessage (hab, NULLHANDLE, IDS MESSAGE 
, BSlzgeot (szMsq), szMsq ); 

WinMessageBox (HWND_DESKTOP, hwndFrame, szMsg, szTitle 
, & MBF ) 


This function and WinLoadString perform an equivalent func- 
tion. 





WinLoadPointer 





Loads a pointer or icon from a resource. 


SYNTAX 


HPOINTER WinLoadPointer (HWND hwndDesktop, HMODULE 
hmod, ULONG 7d) 


PARAMETERS 

hwndDesktop - input 

The desktop window’s handle (HWND_DESKTOP). 

hmod - input 

The handle of the dynamic link library containing the pointer or icon 
resource. You can retrieve the DLL’s module handle with DosLoad- 
Module or DosQueryModuleHandle. If the resource is bound to the 
current executable, pass NULLHANDLE. 

id - input 

The pointer or icon resource identifier. 


RETURNS 


Pointer or icon handle, or NULLHANDLE if an error occurred. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_ INVALID HWND 
Oxl00A - PMERR_RESOURCE_NOT_FOUND 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 


WinCreatePointer -232, WinCreatePointerIndirect -233, 
WinDestroyPointer -237, WinDrawPointer -121, WinSetPointer -254 


NOTES 


This function loads a pointer that you can draw with WinDrawPointer 
or set as the system mouse pointer with WinSetPointer. A program can 
also create a pointer from memory using WinCreatePointer or 
WinCreatePointerIndirect. When the process that loads the pointer or 
icon terminates, PM automatically destroys the pointer or icon. | 





@ WinLoadProcedure 





Retrieves a dynamically loaded function address. 


SYNTAX 
PFNWP WinLoadProcedure (HAB hab, HLIB hitb, PSZ pszProcname) 


PARAMETERS 

hab - input 

Anchor block handle. 

hhb - input 

The DLL module handle returned by WinLoadLibrary or DosLoad- 
Module. 

pszProcname - input 

The name of a function contained in the library. 


RETURNS 


The address of the indicated function, or NULL if an error occurred. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINLOAD 


SEE ALSO 


WinLoadLibrary -241, WinDeleteProcedure -236, 
WinDeleteLibrary -235 
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NOTES 


This function is equivalent to DosQueryProcAddr—it returns the ad- 
dress of a function that is contained in a dynamic library (DLL). When 
you are finished using the function, you should call WinDelete- 
Procedure. 





WinLoadString 


Loads a string from a resource. 


SYNTAX 


LONG WinLoadString (HAB hab, HMODULE hmod, ULONG 
idSiring, LONGcch, PSZ psz) 


PARAMETERS 

hab - input 

Anchor block handle. 

hmod - input 

The handle of the dynamic link library containing the string table re- 
source. You can retrieve the DLL’s module handle with DosLoad- 
Module or DosQueryModuleHandle. If the resource is bound to the 
current executable, pass NULLHANDLE. 

id String - input 

The identifier of a string within the string table. 

cch - input 

The size of the output string. 

psz - output 

The output string where this function copies the string. 


RETURNS 


The returned string’s length, or zero if an error occurred. 
Possible returns from WinGetLastError: 


Oxl00A - PMERR RESOURCE_NOT_FOUND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


246 


OS/2 WARP Presentation Manager API 


SEE ALSO 
WinLoadMessage -241 


NOTES 


This function loads a string from a string table defined in a resource 
file. For example: 


#define IDS_MESSAGE 16 
#define IDS_TITLE 17 


STRINGTABLE 

{ 
IDS_MESSAGE "This 1s a test, this is only a test” 
IDS TITLE “Message Box Title” 


we 


A program could then load the messages and display them using: 


ULONG cb; // string length 
CHAR szTitie(255)> // message box title 
CHAR szMsq [255] // message box msg string 


cb = WinLoadString (hab, NULLHANDLE, IDS_TITLE 
, Sizeof (szTitle), szTitle ); 


cb WinLoadString (hab, NULLHANDLE, IDS_MESSAGE 


, Sizeof (szMsg), szMsg ); 
WinMessageBox (HWND_DESKTOP, hwndFrame, szMsg, szTitle 
« Uy MB OK) 3 


This function and WinLoadMessage perform an equivalent function. 





WinLockPointerUpdate 


Locks the system mouse pointer shape for a specific time interval. 


SYNTAX 

BOOL WinLockPointerUpdate (HWND hwndDeskiop, HPOINTER 
hptr, ULONGulTime) 

PARAMETERS 


hwndDeshtop - input 
The desktop window’s handle (HWND_DESKTOP). 
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hptr - input 

The handle of the pointer that this function uses to set the system 
mouse pointer. 

ulTime - input 

The interval in milliseconds during which the mouse pointer shape is 
fixed. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 


WinCreatePointer -232, WinCreatePointerIndirect -233, 
WinLoadPointer -243, WinSetPointer -254 


NOTES 


This function sets the system mouse pointer shape for the interval 
specified. 
This function is only available in OS/2 2.1 and later. 





WinQueryAccel Table 


Retrieves an accelerator table handle from a frame window or the han- 
dle of the system accelerator table. 


SYNTAX 
HACCEL WinQueryAccelTable (HAB hab, HWND hwndFrame) 


PARAMETERS 

hab - input 

Anchor block handle. 

hwndFrame - input 

Pass the handle of a frame window or NULLHANDLE to query the sys- 
tem accelerator table’s handle. 
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RETURNS 


The accelerator table handle, or NULLHANDLE if the frame has no 
accelerator table or an error occurred. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINACCELERATORS 


SEE ALSO 


WinLoadAccelTable -238, WinCreateAccelTable -230, 
WinSetAccelTable -251, WinTranslateAccel -258, 
WinCreateStdWindow -17, WinDestroyAccelTable -236, 
WinCopyAccelTable -228 


NOTES 


An accelerator table translates keystroke messages into another mes- 
sage, typically WM_COMMAND. PM defines a system accelerator table 
that includes F1 (for help), F10 (release invokes the menu), and so on. 
Applications can also attach private accelerator tables to frame win- 
dows using WinSetAccelTable or the FCF_ACCELTABLE flag in Win- 
CreateStd Window. 

Translation occurs if an application calls WinTranslateAccel, or 
during WinGetMsg, which calls WinTranslateAccel. The system first 
translates keys in a private accelerator table before the system acceler- 
ator table. Thus, a program can override the system table by specifying 
a system key in a private accelerator table. 

A program can dynamically modify either the system accelerator 
table or a private accelerator table by obtaining its handle with this 
function, copying the table to memory with WinCopyAccelTable, mod- 
ifying the memory, creating a new table with WinCreateAccelTable, 
and finally setting the new table with WinSetAccelTable. 





@® WinQueryPointer 


Queries the current system pointer’s handle. 


SYNTAX 
HPOINTER WinQueryPointer (HWND hwndDeskiop) 
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PARAMETERS 


hwndDesktop - input 
The desktop window’s handle (HWND_DESKTOP). 


RETURNS 


The desktop window’s pointer handle, or NULLHANDLE if an error 
occurred. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 
WinSetPointer -254, WinLoadPointer -243, WinQueryPointerInfo -249 





WinQueryPointerInfo 


Retrieves information about a pointer or icon. 


SYNTAX 

BOOL WinQueryPointerInfo (HPOINTER hpi, PPOINTERINFO 
ppin) 

PARAMETERS 

hptr - input 

The handle of the pointer or icon to query. 

pptri - output 


Pass the address of a POJNTERINFO structure that this function fills in: 


typedef struct _POINTERINFO /* ptri */ 
{ 

ULONG fPointer; 

LONG xHotspot; 

LONG yHotspot; 

HBITMAP hbmPointer; 

HBITMAP hbmColor; 

HBITMAP hbmMiniPointer; 

HBITMAP hbmMiniColor; 
} POINTERINFO; 
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fPointer TRUE if hpirrefers to a pointer; FALSE if it’s an icon. 

xHotspot The x-coordinate of the pointer’s hot spot from the point- 
er’s lower left. 

yHotspot The y-coordinate of the pointer’s hot spot from the point- 
er’s lower left. 

hbmPointer A handle to a bitmap that represents the pointer or 
icon. The bitmap has two distinct sections: the top half is an “AND” 
mask, the bottom half an “XOR” mask. PM draws both masks when 
it draws the pointer or icon. This technique allows transparent sec- 
tions. 

hbmColor A handle to a bitmap that contains the color information 
for the pointer or icon. This bitmap is the same width as the bitmap 
passed in hbmPointer and one-half its height. In other words, the 
color bitmap is the same size as the individual masks in the pointer 
bitmap. When PM draws the pointer or icon, it logically “ORS” the 
color bitmap with the result of drawing the “AND” and “OR” masks. 

hbmMiniPointer A handle for a small bitmap. See the previous 
hbmPoinier discussion. 

hbmMiniColor A handle for a small bitmap. See the previous hbm- 
Color discussion. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 
Ox101B-PMERR INVALID HPTR 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 
WinCreatePointer -232, WinCreatePointerIndirect -233 





WinQueryPointerPos 


Retrieves the current mouse pointer’s position. 


SYNTAX 
BOOL WinQueryPointerPos (HWND hwndDeskiop, PPOINTL ppit) 
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PARAMETERS 

hwndDesktop - input 

The desktop window’s handle (HWND_DESKTOP). 

pptl - output 

Pass the address of a POJNTL that this function fills in with the mouse 
pointer coordinates, in pixels, relative to the lower left corner of the 
desktop (screen units). The coordinates reflect the pointer’s position 
from the last call to WinGetMsg or WinPeekMsg. The current position 
may be different since the pointer may have been moved since the last 
time the message queue was read. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 


WinSetPointer -254, WinSetPointerPos -256, 
WinMapWindowPoints -282 





WinSetAccelTable 





Attaches an accelerator table to a frame window or sets the system ac- 
celerator table. 


SYNTAX 

BOOL WinSetAccelTable (HAB hab, HACCEL haccel, HWND 
hwndFrame) 

PARAMETERS 

hab - input 

Anchor block handle. 


haccel - input 
The handle of the accelerator table to attach. Pass NULLHANDLE to 
remove the current accelerator from the frame window or system. 
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hwndFrame - input 

The handle of the frame window to which to attach the accelerator 
table. Pass NULLHANDLE to set the accelerator table as the system ac- 
celerator table. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID_HWND 
Oxl01A - PMERR_ INVALID _HACCEL 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINACCELERATORS 


SEE ALSO 


WinLoadAccelTable -238, WinCreateAccelTable -230, 
WinTranslateAccel -258, WinCreateStdWindow -17, 
WinCopyAccelTable -228, WinQueryAccelTable -247 


NOTES 


An accelerator table translates keystroke messages into another mes- 
sage, typically WM_COMMAND. PM defines a system accelerator table 
that includes F1 (for help), F10 (release invokes the menu), and so on. 
Applications can also attach private accelerator tables to frame win- 
dows using WinSetAccelTable or the FCF_ACCELTABLE flag in Win- 
CreateStdWindow. 

Translation occurs if an application calls WinTranslateAccel, or 
during WinGetMsg, which calls WinTranslateAccel. The system first 
translates keys in a private accelerator table before the system acceler- 
ator table. ‘Thus, a program can override the system table by specifying 
a system key in a private accelerator table. 

A program can dynamically modify either the system accelerator 
table or a private accelerator table by obtaining its handle with Win- 
QueryAccelTable, copying the table to memory with WinCopyAccel- 
Table, modifying the memory, creating a new table with WinCreate- 
AccelTable, and finally setting the new table with WinSetAccelTable. 
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@ WinSetFilelcon 





Assigns an icon to an executable or data file. 


SYNTAX 
BOOL WinSetFileIcon (PSZ pszFilename, PICONINFO picninf) 


PARAMETERS 

pszFilename - input 

Pass the address of a string that contains the path name of an exe- 
cutable or data file. 

picninf - input 

Pass the address of an JCONINFO structure: 


typedef struct _ICONINFO { /* icninf */ 
ULONG cb; 
ULONG fFormat; 
PSZ pszFileName; 
HMODULE hmod; 
ULONG resid; 
ULONG cbiIconData; 
PVOID piconData; 


ww 


ICON TNFO; 


cb The structure’s length, in bytes. 
fFormat One of the following: 


IGON_DATA The plconDaia field points to a BITMAPFILE- 
HEADER or BITMAPFILEHEADER2 that describes the icon. 

ICON_FILE The pszFileName field references a file containing an 
icon definition. 

ICON_CLEAR The system should reset the icon to its default. 

ICON RESOURCE The hmod and resid fields reference an icon 
resource. 


pszFileName Points to a file name string if fFormat is ICGON_FILE. 

hmod Contains a dynamic link library module handle, or NULL- 
HANDLE if fFormat is ICON_RESOURCE. 

resid Contains a resource identifier if Format is IGON_RESOURCE. 

cbIconData ‘The length, in bytes of the icon data. Ignored unless 
Format is ICGON_DATA. 

piconData Points to a BITMAPFILEHEADER or BITMAPFILE- 
HEADER2 that describes the icon if Format is ICON_DATA. 
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RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID HWND 
0x1003 - PMERR_PARAMETER_OUT_OF_RANGE 
Ox100a - PMERR_ RESOURCE _NOT_FOUND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 


WinLoadFilelIcon -239, WinFreeFileIcon -238, 
WinQuerysysPointerData -339 


NOTES 
This function assigns the icon as the file’s ICON extended attribute. 





@ WinSetPointer 





Sets the current mouse pointer for the system. 


SYNTAX 
BOOL WinSetPointer (HWND hwndDesktop, HPOINTER hpitr) 


PARAMETERS 


hwndDesktop - input 

The desktop window's handle (HWND_DESKTOP). 

hptr - input 

The pointer handle to assign as the current system mouse pointer. Pass 
NULLHANDLE to remove the system mouse pointer. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_ Ox101b - PMERR_ INVALID _ 
HWND HPTR 

0Ox205E - PMERR_INV_CUR- 
SOR_BITMAP 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 


WinCreatePointer -232, WinCreatePointerIndirect -233, 
WinLoadPointer -243, WinQuerySysPointer -337 


NOTES 


This function sets the current system mouse pointer. Every window 
procedure must call this function every WM_MOUSEMOVE message, 
either by calling the default window procedure, which sets the default 
mouse pointer, or by calling this function to set a custom mouse 
pointer. 





WinSetPointerOwner 





Lets a pointer be shared between processes. 


SYNTAX 

BOOL WinSetPointerOwner (HPOINTER hpi, PID pid, BOOL 
Destroy) 

PARAMETERS 

hptr - input 

The handle of the pointer to share. 

pid - input 


Identifies the process with which to share the pointer. Pass zero to 
share with all processes. 


{Destroy - input 
Pass TRUE to let the new owner destroy the pointer, FALSE otherwise. 
RETURNS 


TRUE if successful, FALSE otherwse. 
Possible returns from WinGetLastError: 


Ox101b - PMERR_INVALID_HPTR 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 
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SEE ALSO 


WinCreatePointer -232, WinCreatePointerIndirect -233, 
WinLoadPointer -243, WinDestroyPointer -237 


NOTES 


Normally, when a process creates or loads a pointer, it can only be used 
by that process. This function enables a process to create or load a 
pointer and make it available to another process. This function does 
not notify the second process of the pointer’s handle; the first process 
must pass the handle to the second using some form of interprocess 
communication or a private message. 

If you pass FALSE for /Destroy, or zero for pid, PM will never deal- 
locate the resources for the pointer. You must ensure that some 
process sets the owner with TRUE for /Destroy and calls WinDestroy- 
Pointer. 

This function is only available in OS/2 2.1 and later. 





@ WinSetPointerPos 





Changes the current mouse pointer’s position. 


SYNTAX 
BOOL WinSetPointerPos (HWND hwndDeskiop, LONG x, LONG y) 


PARAMETERS 

hwndDesktop - input 

The desktop window’s handle (HWND_DESKTOP). 

x - input 

The new pointer x-coordinate in pixels, relative to the desktop’s lower 
left corner (screen units). 

y - input 

The new pointer y-coordinate in pixels, relative to the desktop’s lower 
left corner (screen units). 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 
WinQueryPointerPos -250, WinMapWindowPoints -282 





W inShowPointer 





Increments or decrements the system mouse pointer’s hide count. 


SYNTAX 
BOOL WinShowPointer (HWND hwndDesktop, BOOL fShow) 


PARAMETERS 


hwndDesktop - input 

The desktop window's handle (HWND_DESKTOP). 

{Show - input 

TRUE to decrement the hide count, FALSE to increment the hide 
count. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 
WinQuerySsysValue -342 


NOTES 


PM maintains a hide count (sometimes called the hide level) for the 
mouse pointer. If the hide count is zero, the pointer is visible; if the 
count is greater than zero, PM hides the pointer. This function incre- 
ments or decrements the hide count, thus showing or hiding the 
pointer. This function will not decrement the hide count below zero. 
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If during boot, PM detects that the computer has no pointing de- 
vice, it initializes the hide count to one, thus hiding the pointer. If 
there is a pointing device, PM sets the the hide count to zero. A pro- 
gram can query the current hide count value by calling WinQuery- 
SysValue, specifying the SV_POINTERLEVEL option. 





@ WintTranslateAccel 





Translates keystroke messages. 


SYNTAX 


BOOL Win TranslateAccel (HAB hab, HWND hwnd, HACCEL haccel, 
POQMSG pamsg) 


PARAMETERS 

hab - input 

Anchor block handle. 

hwnd - input 

Destination window handle. 

haccel - input 

Pass the handle of the accelerator table that this function will use to 
translate the WM_CHAR message, or pass NULLHANDLE to use the 
current accelerator table. 

pqmsg - input/output 

On input, pass the address of a QMSG structure containing an untrans- 
lated message. This function will modify the message identifier and pos- 
sibly the message parameters to translate the message to a WM_COM- 
MAND, WM_SYSCOMMAND, or WM_HELP message, depending on the 
accelerator table. 


typedef struct _QMSG /* qmsg */ 
{ 

HWND hwnd; 

ULONG msg; 

MPARAM mpl; 

MPARAM mp2; 

ULONG time; 

POINTL ptl; 

ULONG reserved; 
} QMSG; 
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hwnd The handle of the window receiving the message. 

msg ‘The message identifier. 

mpl _ The first message parameter. 

mp2 The second message parameter. 

time ‘The time the message was generated. 

ptl The mouse pointer coordinates at the time the message was gen- 
erated. 

reserved Reserved. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x101A - PMERR_INVALID_HACCEL 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINACCELERATORS 


SEE ALSO 


WinCreateAccelTable -230, WinLoadAccelTable -238, 
WinCopyAccelTable -228 


NOTES 


Most PM programs need not call this function explicitly, as both 
WinGetMsg and WinPeekMsg call it implicitly. 

Accelerator tables translate WM_CHAR messages into WM_COM- 
MAND (same as menus), WM_SYSCOMMAND (same as the system 
menu), or WM_HELP messages. This examines the provided message 
and accelerator table and modifies the message if there is a corre- 
sponding entry in the accelerator table. 

Since many accelerators correspond to menu items before trans- 
lating (for example, Shift+Ins for Edit-Paste), this function first queries 
any corresponding menu item to determine if the menu item is dis- 
abled. Ifit is, this function translates the message to WM_NULL instead 
of WM_COMMAND or WM_SYSCOMMAND. 








resentation Manager provides the Information Presentation 
Facility (IPF) or Help Manager to enable programs to provide the 
user with context-sensitive help. The developer typically writes the text 
for the help screens in a .IPF file, and marks the text with IPF tags to 


. format the help screens. The developer usually then writes a series of 


tables in the program ’s resource file that describe when IPF should dis- 
play each help screen. The window procedure must also process mes- 
sages from IPF to aid IPF in choosing which screen to display. In addi- 
tion to those tasks, the developer must also initialize and shut down 
IPF using the functions described in this chapter. 


Help Functions 
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WinAssociateHelpInstance connects an instance of IPF with a frame 
window (pg 261). 

WinCreateHelpInstance creates an IPF instance (pg 262). 
WinCreateHelpTable creates a help table in memory (pg 264). 
WinDestroyHelpInstance deletes an IPF instance (pg 266). 
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WinLoadHelpTable loads a help table from a resource (pg 267). 
WinQueryHelpInstance returns the current help instance handle 


(pg 268). 





WinAssociateHelpInstance 


Connects an instance of IPF with a frame window. 


SYNTAX 

BOOL WinAssociateHelpInstance (HWND hwndHelp, HWND 
hwndFrame) 

PARAMETERS 


hwndHelp - input 

The IPF instance handle returned by WinCreateHelpInstance, or 
NULLHANDLE to disassociate a frame window and a help instance. 
hwndFrame - input 

The handle of the frame window to which to associate the help in- 
stance. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - HMERR_NO_FRAME WND_IN_CHAIN 
Ox1002 - HMERR_INVALID_ASSOC_APP_WND 
0x1003 - HMERR_INVALID_ASSOC_HELP_INST 


OTHER INFO 
Include file: pmhelp.h Define: INCL_WINHELP 


SEE ALSO 
WinCreateHelpInstance -262 


NOTES 


After creating a help instance, the program needs to associate the help 
instance with a chain of windows so that IPF can process help requests 
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from the user. The chain of windows starts with hwndFrame and in- 
cludes all windows owned by or children of the frame. Since dialogs 
are typically owned by the frame window that displayed the dialog, you 
typically only need to issue this call multiple times if you have unowned 
modeless dialogs or multiple main windows. Each unowned modeless 
dialog or main window must have its own association chain. 

WinGetLastError returns HMERR INVALID ASSOC_APP WND 
if you pass this function a bad frame window handle, and returns 
HMERR_INVALID_ASSOC_HELP_INST if you pass it a bad help in- 
stance handle. 





@® WinCreateHelpinstance 


Creates an IPF instance. 


SYNTAX 
HWND WinCreateHelpInstance (HAB hab, PHELPINIT phz) 


PARAMETERS 

hab - input 

Anchor block handle. 

phi - input 

Pass the address of a HELPINIT structure: 
typedef struct _HELPINIT f* Tanit */ 

{ 


ULONG ele. 
ULONG ulReturnCode; 
PSZ pszTutorialName; 


PHELPTABLE phtHelpTable; 

HMODULE hmodHelpTableModule; 
HMODULE hmodAccelActionBarModule; 
ULONG idAccelTable; 


ULONG idActionBar; 
PSZ pszHelpWindowTitle; 
ULONG £fShowPanelld; 
PSZ pszHelpLibraryName; 


} HELPINIT, 
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cb The structure length, in bytes. 

ulReturnCode This function returns an error code here (same as re- 
turned by WinGetLastError). 

pszTutorialName Name of tutorial program, or NULL if the pro- 
gram has no tutorial. 

phtHelpTable ‘The help table can either be defined in memory or 
from a resource. If you wish to create a help table in memory with 
WinCreateHelpTable or load a help table into memory with Win- 
LoadHelpTable, pass NULL here and then create or load the help 
table after creating the help instance. If you want this function to 
load the help table from a resource, pass a ULONG with Oxffff in the 
16 most significant bits and the help table identifier in the 16 least 
significant bits. 

hmodHelpTableModule If you want this function to load the help 
table from a resource (see the phiHelpTable field), pass the module 
handle of the dynamic link library containing the help table, or pass 
NULLHANDLE if the help table resource is bound to the current 
executable. 

hmodAccelActionBarModule If you want IPF to use a custom menu 
and accelerator table, you must define them as resources and bind 
them to a dynamic link library and pass the DLL module handle 
here. If you want IPF to use its standard menu and accelerator table, 
pass NULLHANDLE for this field. 

idAccelTable If you are using a custom accelerator table (see 
hmodAccelActionBarModule), pass the accelerator resource identifier 
here. Pass zero for IPF to use its standard accelerator table. 

idActionBar If you are using a custom menu (see hmodAccelAction- 
BarModule), pass the menu resource identifier here. Pass zero for 
IPF to use its standard menu table. 

pszHelpWindowTitle IPF displays help screens inside of a main IPF 
window. Pass a string for the main IPF window title here. 

fShowPanelld Specify one of the following: 
CMIC_SHOW_PANEL ID displays the panel (help screen) iden- 

tifier in the title bar—useful for debugging. 
CMIC_HIDE PANEL ID IPF does not display the panel identi- 
fier. 

pszHelpLibraryName Pass a string that specifies the file name of the 
binary help file created by the help compiler. You can specify several 
files, separating them with blanks. At runtime IPF looks for this file 
starting in the current directory, followed by the directories speci- 
fied by the HELP environment variable. 
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RETURNS 
The IPF instance window handle or NULLHANDLE if an error occurred. 
Possible returns from WinGetLastError: 


0x2003 - HMERR_OPEN_LIB_FILE 
0x2004 - HMERR_READ_ LIB FILE 
0x2006 - HMERR_INVALID_LIB_FILE 
0x2007 - HMERR_NO_MEMORY 


OTHER INFO 
Include file: pmhelp.h Define: INCGL_WINHELP 


SEE ALSO 


WinLoadHelpTable -267, WinCreateHelpTable -264, 
WinAssociateHelpInstance -261, WinDestroyHelpInstance -266 


NOTES 


This function creates an invisible window that acts as the IPF help in- 
stance. You must associate the help instance with a chain of windows 
before IPF will process help requests for your program. 

It’s important to destroy the help instance when your program ter- 
minates, otherwise, there’s a possibility of a memory leak. 





@ WinCreateHelp Table 


Creates a help table in memory. 


SYNTAX 
BOOL WinCreateHelpTable (HWND hwndHelp, PHELPTABLE pht) 


PARAMETERS 

hwndHelp - input 

An IPF help instance handle returned by WinCreateHelpInstance. 
pht- input 

Pass the address of a help table, which is an array of the HELPTABLE 
structures shown below. The last structure in the array should have 
zero for all of its fields to act as a terminator. 
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typedef struct _HELPTABLE P* be ey 

{ 
USHORT 1dAppWindow; 
PHELPSUBTABLE phstHelpSubTable; 
USHORT 1dExtPanel; 

} HELPTABLE; 


idAppWindow The window identifier for a frame window or for a dia- 
log window. This window must be part of the window chain associ- 
ated with the help instance (see WinAssociateHelpInstance, pg 261). 

phstHelpSubTable Pass the address of a help subtable containing 
one or more entries (see below). 

idExtPanel ‘The panel identifier of the extended help panel for the 
frame window or dialog. This identifier must match an entry in the 
marked-up IPF file. 


Each help subtable contains a count USHORT followed by an array of 
entries, each of which has two or more USHORTs. The count USHORT 
must contain the number of USHORTs for each subsequent subtable 
entry. The minimum is two: the first USHORT of each entry must con- 
tain a window or menu identifier, the second an IPF panel identifier. 
The last entry must contain zero in all USHORTs; this terminates the 
array. You can place more than two USHORT3S in each entry, but IPF 
only examines the first two. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1008 - HMERR_ HELP INST CALLED INVALID 
0x1009 - HMERR_ HELPTABLE UNDEFINE 
0Ox100a - HMERR_HELP_INSTANCE_UNDEFINE 
Ox100b - HMERR_HELPITEM_ NOT_FOUND 
0x100c - HMERR_INVALID_HELPSUBITEM_ SIZE 
Ox100d - HMERR_HELPSUBITEM_NOT_FOUND 


OTHER INFO 
Include file: pmhelp.h Define: INCL_WINHELP 


SEE ALSO 
WinCreateHelpInstance -262, WinLoadHelpTable -267 
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NOTES 


You can call this function after creating a help instance to connect the 
help instance with a help table. 


The help table is a two-level hierarchy: the first level, called the 


main help table (or simply help table) consists of entries that: 


1. 


Oo 


Identify a standard window frame or dialog frame window. You can 
define a help screen for the window, called the extended help 
panel, and a separate help screen for each of the frame’s child win- 
dows. 


. Point to the help subtable that describes the frame’s child windows. 


For a standard window, the child windows are typically menus, while 
for a dialog, the child windows are dialog controls. 


. Identify the extended help screen (panel) if the user asks for help 


and none of the child windows have the input focus or a separate 
help panel. Typically, this matches a panel identifier defined in the 
marked-up .IPF file. 


You need to define a separate main help table for each chain of 


windows in your program. A chain of windows consists of a top-level 
window and its child windows and windows owned by the main window. 


— 


NO 


Each help subtable consists of entries that: 


Identify a child window or a menu item. If the help subtable is for a 
standard window, the entries typically are for menu items. If the 
subtable is for a dialog, the entries are typically the dialog control 
windows. 


. Identify the help screen (panel) for the child window or menu 


item. Typically, these match panel identifiers defined in the 
marked-up .IPF file. 





@ WinDestroyHelpInstance 


Deletes an IPF instance. 


SYNTAX 
BOOL WinDestroyHelpInstance (HWND hwndHelp) 
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PARAMETERS 
hwndHelp - input 
An IPF help instance handle returned by WinCreateHelpInstance. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1004 - HMERR INVALID DESTROY _HELP_INST 


OTHER INFO 
Include file: pmhelp.h Define: INCL_WINHELP 


SEE ALSO 
WinCreateHelpInstance -262 





WinLoadHelp Table 


Loads a help table from a resource. 


SYNTAX 


BOOL WinLoadHelpTable (HWND hwndHelp, ULONG 7d, 
HMODULE hmod) 


PARAMETERS 

hwndHelp - input 

An IPF help instance handle returned by WinCreateHelpInstance. 

id - input 

The resource identifier of the main help table. 

hmod - input 

The module handle of the dynamic link library containing the help re- 
source, or NULLHANDLE if the resource is bound to the current exe- 
cutable. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1008 - HMERR_HELP_INST_CALLED_INVALID 
0x1009 - HMERR_ HELPTABLE_UNDEFINE 
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Ox100a - HMERR_HELP_INSTANCE_UNDEFINE 
0Ox100b - HMERR_HELPITEM_NOT_FOUND 
Ox100c - HMERR_INVALID HELPSUBITEM_SIZE 
0Ox100d - HMERR_HELPSUBITEM_NOT_FOUND 
0x2004 - HMERR READ LIB FILE 


OTHER INFO 
Include file: pmhelp.h Define: INCGL_WINHELP 


SEE ALSO 
WinCreateHelpInstance -262, WinLoadHelpTable -267 


NOTES 


You can call this function after creating a help instance to connect the 
help instance with a help table. It is equivalent to sending the HM_ 
LOAD_HELP_TABLE message to the help instance. 

If this function detects an error, it generates the HM_ERROR mes- 
sage, in which it passes the error code. For example, if you pass an in- 
valid resource identifier, this function generates the HM_ERROR mes- 
sage with mpl = HMERR_READ_LIB_FILE. 





@ WinQueryHelpinstance 


Returns the current help instance handle. 


SYNTAX 
HWND WinQueryHelpInstance (HWND hwnd) 


PARAMETERS 
hwnd - input 
The window for which to query the help instance. 


RETURNS 


The help instance window handle, or NULLHANDLE if there is no 
help instance or an error occurred. 
Possible returns from WinGetLastError: 


0x1005 - HMERR_NO_HELP_INST_IN_CHAIN 
0x1007 - HMERR_INVALID_QUERY_APP_WND 
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OTHER INFO 
Include file: pmhelp.h Define: INCL_WINHELP 


SEE ALSO 
WinAssociateHelpInstance -261 


NOTES 


This function uses the input window handle and attempts to find an as- 
sociated help instance. If the specified window has no help instance, 
this function traverses up the parent and owner hierarchies until it 
finds an associated help instance or it reaches the top of both hierar- 
chies, in which case it returns NULLHANDLE. 


@15 
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henever a program creates a window, Presentation Manager al- 

locates an internal data structure called the window data struc- 
ture and uses it to store the window's characteristics, for example its 
style. A program can use the functions described in this chapter to ex- 
plicitly read and write fields in the window data structure. In addition, 
some of these functions implicitly modify the window data structure. 
For example, WinShowWindow changes the WS_VIS/BLE style flag that 
is part of the style field in the window data structure. 


System-Defined Information vs. Application-Defined 


In addition to the system-defined area, PM also allows programs to re- 
serve and use space in the window data structure for their own use. 
This extra space is sometimes referred to as the window words. To do so, 
the program must first reserve the space in WinRegisterClass (pg 28), 
then PM will allocate the the extra space when the program creates the 
window. The program can use functions described in this chapter, such 
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as WinSetWindowULong, to read and write the storage. Traditionally, 
PM programs have limited the size of the storage to less then 20 
bytes—if a program needs more, the program can allocate private stor- 
age and store its pointer in the window words. 

A common use for this storage is to avoid using static variables in 
the window procedure, which cause problems if the program creates 
more than one window of the same class simultaneously. In that case, 
there is only one copy of the statics, even though there is more than 
one window. The program can instead store the variables as part of the 
window words, since PM will allocate a separate window data structure 
for each window. 

Many preregistered windows use the window words for this pur- 
pose. For example, a WC_BUTTON window stores a pointer to its text 
in the window words. In addition, most predefined windows reserve 
space for the first four bytes of the window words but don’t use them— 
this field, sometimes referred to as QWL_USER, is available for pro- 
grams that create the window. 


Presentation Parameters 


Presentation parameters are identity-value pairs that a program can 
use when painting to the window. Most presentation parameters in- 
volve color, but some specify a font. Whenever the user or a program 
changes a window's presentation parameters, PM attaches the presen- 
tation parameters to the window’s data structure—the window proce- 
dure can query them with WinQueryPresParam (pg 285). A program 
can change a window's presentation parameters with WinSetPres- 
Param (pg 307) and remove them from the window data with Win- 
RemovePresParam (pg 300). 

The user changes presentation parameters using the Workplace 
Shell’s Color Palette, Font Palette, and Scheme Palette objects (usually 
found in the OS/2 System Setup folder). When the user drags from 
the font or color palette, the target window receives the WM_PRES- 
PARAMCHANGED message and can query its presentation parameters 
and repaint. The user has two options with the scheme palette: if he or 
she drags to a window while pressing the Alt key, PM changes the sys- 
tem default colors and fonts and passes all windows the WM_SYSVAL- 
UECHANGED message. A program can query the defaults with 
WinQuerysysColor (pg 333) and WinQuerySysValue (pg 342) which 
are described in Chapter 14 on System Information. If the user drags 
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from the scheme palette without holding the Alt key, PM passes the 
WM_PRESPARAMCHANGED message to the target frame window and 
attaches the presentation parameters to the frame. The frame then in- 
validates all of its descendants so they repaint. A window owned by the 
frame (such as a pushbutton on a dialog) can use WinQueryPres- 
Param (pg 285) to query the presentation parameters attached to its 
owner. 


Window Information Functions 





WinBeginEnumWindows starts a window enumeration loop (pg 274). 
WinEndEnumWindows ends a window enumeration loop (pg 274). 
WinGetMaxPosition retrieves information about a window’s makxi- 
mized state (pg 275). 

WinGetMinPosition retrieves information about a window’s mini- 
mized state (pg 277). 

WinGetNextWindow retrieves a window handle in an enumeration 
loop (pg 278). 

WinIsChild determines whether a window handle refers to a child win- 
dow (pg 279). 

WinIsWindow determines if a window handle is valid (pg 280). 
WinIsWindowShowing determines if the user can see any part of a win- 
dow (pg 281). 

WinIsWindowVisible returns the window's visible flag (pg 281). 
WinMapWindowPoints converts coordinates from one window to an- 
other (pg 281). 

WinMultWindowFromIDs returns window handles of child windows, 
given their identifiers (pg 283). 

WinQueryPresParam retrieves a window's presentation parameters 
(pg 285). 

WinQueryWindow retrieves a window handle, given a related window’s 
handle (pg 289). 

WinQueryWindowPos retrieves a window’s size and position (pg 290). 
WinQueryWindowProcess retrieves a window’s process and thread 
identifiers (pg 292). 

WinQueryWindowPtr retrieves a pointer from the window data struc- 
ture (pg 293). 
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WinQueryWindowRect retrieves the rectangle containing the win- 
dow’s coordinates (pg 294). 

WinQueryWindowText retrieves a window’s text string (pg 295). 
WinQueryWindowTextLength retrieves the number of characters in a 
window’s text string (pg 296). 

WinQueryWindowULong retrieves a 32-bit value from the window data 
structure (pg 296). 

WinQueryWindowUShort retrieves a 16-bit value from the window 
. data structure (pg 298). 

WinRemovePresParam deletes a presentation parameter from a win- 
dow (pg 300). 

WinRestoreWindowPos restores a window’s size, position, and flags 
from a profile (pg 301). 

WinSaveWindowPos lets a frame window save an array of window posi- 
tion structures (pg 302). 

WinSetMultWindowPos sets several windows’ size, position, flags, and 
Z-order (pg 303). 

WinSetOwner changes a window's owner window (pg 305). 
WinSetParent changes a window's parent window (pg 306). 
WinSetPresParam assigns a presentation parameter to a window 
(pg 307). 

WinSetWindowBits sets bit flags into the window data structure 
(pg 310). 

WinSetWindowPos sets a window's size, position, flags, and Z-order 
(pg 311). 

WinSetWindowPtr sets a 32-bit value into the window data structure 
(pg 314). 

WinSetWindowText assigns a window’s text string (pg 315). 
WinSetWindowULong sets a 32-bit value into the window data struc- 
ture (pg 316). 

WinSetWindowUShort sets a 16-bit value into the window data struc- 
ture (pg 317). 

WinShowWindow sets or clears the window’s visible flag (pg 319). 
WinStoreWindowPos saves a window’s size, position, and flags to a pro- 
file (pg 320). 

WinSubclassWindow sets the window’s window procedure address 
(pg 321). 

WinWindowfFromID retrieves a child window’s handle, given its identi- 
fier (pg 322). 

WinWindowFromPoint retrieves a window handle, given a coordinate 


point (pg 323). 
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@ WinBeginEnumWindows 


Starts a window enumeration loop. 


SYNTAX 
HENUM WinBeginEnumWindows(HWND hwndParent) 


PARAMETERS 


hwndParent - input 

The parent window for which to enumerate child windows. Pass 
HWND_DESKTOP to enumerate all visible windows and HWND_OB- 
JECT to enumerate all invisible windows that have the object window as 
an ancestor. 


RETURNS 
An enumeration handle, or NULLHANDLE if an error occurred. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinGetNextWindow -278, WinEndEnum Windows -274 


NOTES 


When you issue this function, PM builds an internal tree containing 
the handles of all the child windows of hwndParent. You typically pass 
the returned enumeration handle to WinGetNextWindow in a loop, 
until it returns NULLHANDLE. You must then call WinEndEnum- 
Windows so PM can free the internal storage. 

This function constructs the tree statically, so if changes are made 
to the actual window hierarchy, the enumeration loop will not see the 
changes. 





@® WinEndEnumWindows 





Ends a window enumeration loop. 
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SYNTAX 
BOOL WinEndEnumWindows(HENUM henum) 


PARAMETERS 
henum - input 
A window enumeration handle returned by WinBeginEnumWindows. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1l01c - PMERR_INVALID HENUM 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinBeginEnum Windows -274, WinGetNextWindow -278 


NOTES 


This function frees internal storage allocated by 
WinBeginEnum Windows. 





WinGetMaxPosition 





Retrieves information about a window’s maximized state. 


SYNTAX 
BOOL WinGetMaxPosition(HWND hwnd, PSWP pswp) 


PARAMETERS 

hwnd - input 

The handle of the window to query. 

pswp - output 

Pass the address of an SWP structure that this function fills in: 
typedef struct _SWP /* swp */ 


{ 
ULONG f1; 
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LONG ey; 
LONG Cx} 
LONG vy 
LONG x; 


HWND hwndInsertBehind; 
HWND hwnd; 
ULONG ulReservedl; 
ULONG ulReserved2; 

} SWP; 


fl A combination of SWP flags that you can use in a call to 
WinSetWindowPos. See WinSetWindowPos for a description of the 
flags. 

cy ‘The maximized window’s height in pixels. 

cx The maximized window's width in pixels. 

y The window’s y-coordinate, in pixels, relative to its parent's lower 
left. 

x The window’s x-coordinate, in pixels, relative to its parent’s lower 
left. 

hwndInsertBehind The window’s sibling that is immediately on top 
of it in the stack of windows. 

hwnd The window’s handle. This field is used by the WinSetMult- 
WindowPos function, which uses this same structure. 

ulReservedl Reserved. 

ulReserved2 Reserved. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinGetMinPosition -277, WinQueryTaskSizePos -416 


NOTES 


This function is normally used on frame windows. 
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@ WinGetMinPosition 





Retrieves information about a window’s minimized state. 


SYNTAX 

BOOL WinGetMinPosition( HWND hwnd, PSWP pswp, 
PPOINTL ppi/) 

PARAMETERS 

hwnd - input 

The handle of the window to query. 

pswp - output 


Pass the address of an SWP structure that this function fills in: 


typedef struct _SWP /* swp */ 
{ 


ULONG f1; 
LONG Cy; 
LONG Cx; 
LONG vs 
LONG x 


HWND hwndInsertBehind; 
HWND hwnd; 
ULONG ulReserved1; 
ULONG ulReserved2; 

} SWP; 


fl A combination of SWP flags that you can use in a call to 
WinSetWindowPos. See WinSetWindowPos for a description of the 
flags. 

cy The minimized window’s height in pixels. 

cx The minimized window’s width in pixels. 

y The window's y-coordinate, in pixels, relative to its parent’s lower 
left. 

x The window’s x-coordinate, in pixels, relative to its parent’s lower 
left. 

hwndInsertBehind ‘The window’s sibling that is immediately on top 
of it in the stack of windows. 

hwnd The window's handle. This field is used by the WinSetMult- 
WindowPos function, which uses this same structure. 
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ulReservedl Reserved. 
ulReserved2 Reserved. 


pptl - input 

Pass the address of a POJNTL structure containing the preferred coor- 
dinates of the minimized position. Pass NULL for this argument to let 
PM choose the coordinates. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinGetMaxPosition -275, WinQueryTaskSizePos -416 


NOTES 


This function is normally used on frame windows. 





@ WinGetNextWindow 





Retrieves a window handle in an enumeration loop. 


SYNTAX 
HWND WinGetNextWindow(HENUM henum) 


PARAMETERS 
henum - input 
A window enumeration handle returned by WinBeginEnumWindows. 


RETURNS 


The next child window handle or NULLHANDLE if there are no more 
child windows, or if an error occurred. 
Possible returns from WinGetLastError: 


Ox1l01c - PMERR_INVALID_HENUM 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinBeginEnum Windows -274, WinEndEnum Windows -274, 
WinEnumDlegltem -177 


NOTES 


Before issuing this function, you must call WinBeginEnum Windows, 
and when you are finished enumerating, you must call WinEnd- 
EnumWindows. 

Programs typically call this function in a loop to retrieve all of the 
child windows for a given parent (specified in WinBeginEnum- 
Windows). This function returns the child window handles in their Z- 
order, highest to lowest. The child window with the highest Z-order is 
“on top” in the stack of siblings. After returning all of the child window 
handles, if you call this function again, it returns NULLHANDLE— 
many programs use that return value as a trigger to exit the enumera- 
tion loop. If you call the function again after it returns NULLHAN- 
DLE, it starts over, returning the handle of the child window highest in 
the Z-order. 

This function only returns direct children of the hwndParent spec- 
ified in WinBeginEnumWindows. To obtain the handles of descendant 
windows farther into the hierarchy, you must begin another enumera- 
tion loop. 





WinlsChild 





Determines whether a window handle refers to a child window. 


SYNTAX 
BOOL WinIsChild HWND hwnd, HWND hwndParent) 


PARAMETERS 

hwnd - input 

The handle of the window to test. 
hwndParent - input 

The handle of the possible parent window. 
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RETURNS 


TRUE if hwnd is a descendant of hwndParent, FALSE if not. If hwnd is 
the same as hwndParent, this functions returns TRUE. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinIsWindow -280, WinSetParent -306 





@ WinlsWindow 


Determines if a window handle is valid. 


SYNTAX 
BOOL WinIsWindow(HAB hab, HWND hwnd) 


PARAMETERS 

hab - input 

Anchor block handle. 

hwnd - input 

The handle of the window to test. 
RETURNS 


TRUE if the handle refers to a valid window, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinIsChild -279 
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@ WinlsWindowShowing 


Determines if the user can see any part of a window. 


SYNTAX 
BOOL WinIsWindowShowing (HWND hwnd) 


PARAMETERS 
hwnd - input 
The handle of the window to test. 


RETURNS 
TRUE if any part of the window is visible, FALSE if not. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinShowWindow -319, WinInvalidateRect -138, 
WinIsWindowVisible -281, WinQueryVisibleRegion -144 


NOTES 


This function is useful for programs that draw to the window in re- 
sponse to messages that are not generated by the user; for example, a 
communication program that displays incoming characters could de- 
cide not to write to the window if no part of the window is visible. 

This function differs from WinIsWindowVisible because that call 
simply checks the window’s visible flag, which could be true even if the 
window was hidden behind another window. 





@ WinlsWindowVisible 





Returns the window’s visible flag. 
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SYNTAX 
BOOL WinIsWindowVisible(HWND hwnd) 


PARAMETERS 
hwnd - input 
The handle of the window to test. 


RETURNS 


TRUE if the window and all of its ancestors up the parent tree have 
their WS_ VISIBLE bit set, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinIsWindowShowing -281, WinShowWindow -319, 
WinEnableWindowUpdate -86 


NOTES 


This function examines the WS_VISIBLE bit in the specified window’s 
data structure and all of its ancestors, and returns TRUE only if all of 
them are set. 

This function can return TRUE but the user might not see the 
window because it is covered by other windows. You can call 
WinIsWindowShowing to determine if the user can see any part of the 
window. 





@ WinMapWindowPoints 


Converts coordinates from one window to another. 


SYNTAX 


BOOL WinMapWindowPoints(HWND hwndSource, HWND hwndDest, 
PPOINTL apil, LONG cPoinis) 
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PARAMETERS 


hwndSource - input 

The handle of the window from which to convert coordinates. Pass 
HWND_DESKTOP to convert from desktop (screen) coordinates. 
hwndDest - input 

The handle of the window to which to convert coordinates. Pass 
HWND_DESKTOP to convert to desktop (screen) coordinates. 

aptl - input/output 

Pass the address of an array of POIJNTL structures. Before calling this 
function, initialize the points to coordinates (in pixels) relative to the 
source window's lower left corner. This function modifies the points to 
be relative to the destination window’s lower left corner. 

cPoints - input 

The number of points in the apil array. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinMapDIgPoints -183 


NOTES 


Since this function works in device units (pixels), it ignores any trans- 
forms set into a presentation space. 

Since a RECTL data structure contains two contiguous POINTLs, 
you can convert rectangles by passing the address of the rectangle and 
specifying a count of two. 





WinMultWindowFromI!IDs 





Returns window handles of child windows, given their identifiers. 
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SYNTAX 


LONG WinMultWindowFromIDs(HWND hwndParent, PHWND 
ahwnd, ULONG wlFirst, VLONG 
ulLast) 


PARAMETERS 


hwndParent - input 

The handle of the parent window. 

ahwnd - output 

Pass the address of an array of HWNDs that this function fills in. ‘The ar- 
ray must be large enough to hold (ulLasi-ulFirst)+1 window handles. 
ulFirst - input 

Smallest numerical window identifier. 

ulLast - input 

Largest numerical window identifier. 


RETURNS 


The number of window handles returned, or zero if an error occurred 
or no child windows were found with the range of identifiers. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_ INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinWindowFromID -322, WinQueryWindowUShort -298 


NOTES 


This function lets you query multiple child window handles, given the 
parent window handle and the range of child window identifiers. ‘The 
window creator specifies the window identifier. PM stores the identifier 
in the new window’s window data structure (stored with WinSetWin- 
dowUShort with QWS_JD). 

After calling this function, the output array contains the window 
handles. The first element of the array (index 0 in the C language), con- 
tains the handle for the window with ulFirst, and this function fills the re- 
maining indexes consecutively. If there is a gap in the range of window 
identifiers (for example, a child window with that identifier does not ex- 
ist), this function returns NULLHANDLE in the array for that position. 
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If you need several window handles, and their identifiers are con- 
tiguous, this function is faster than calling WinWindowFromID repeat- 
edly. 





WinQueryPresParam 


Retrieves a window’s presentation parameters. 


SYNTAX 


ULONG WinQueryPresParam(HWND hwnd, ULONG wlPP1, 
ULONG ulPP2, PULONG pulPPRei, 
ULONG cb, PVOID p, ULONG /!) 


PARAMETERS 

hwnd - input 

The window to query. 

ulPPI - input 

The first presentation parameter identifier to query. See WinSetPres- 
Param for a listing of identifiers. You can pass zero for this argument. 
ulPP2 - input 

The second presentation parameter identifier to query. See WinSet- 
PresParam for a listing of identifiers. You can pass zero for this argu- 
ment. 

pulPPRet - output 

Pass the address of ULONG in which this function returns the presen- 
tation parameter identity, if any. This will be one of the two possible 
identifiers specified by wlPPI and ulPP2. If no presentation parameters 
are found, this function will return zero here. You can pass NULL for 
this argument—for example, if you set either ulPPI or ulPP2 to zero, 
there’s no need for this argument, since only one identfier was 
queried, and the return value of this function tells you if it was re- 
turned. 

cb - input 

The size, in bytes, of the next argument. 

p -output 

This function returns the value of one of the presentation parameter 
identifiers specified in ulPPI and ulPP2. The function truncates the re- 
turned value, if necessary, to the size specified in the cb argument. 
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fl- input 

Any combination of these flags: 

OPF _IDICOLORINDEX You can specify this flag if the first presen- 
tation parameter identity (w/PP1) requests a color index value (for 
example, PP_FOREGROUNDCOLORINDEX), and you want this func- 
tion to convert the color index to RGB and return the RGB value. 
This is useful if you have set the presentation space into RGB mode 
using GpiCreateLogColorTable. 

OPF_ID2COLORINDEX You can specify this flag if the second pre- 
sentation parameter identity (ulPP2) requests a color index value 
(for example, PP_FOREGROUNDCOLORINDEX), and you want this 
function to convert the color index to RGB and return the RGB 
value. This is useful if you have set the presentation space into RGB 
mode using GpiCreateLogColorTable. 

QPF NOINHERIT Normally, this function traverses up the owner 
window hierarchy to find a presentation parameter. You can specify 
this flag so that this function queries only the window specified by 
hwnd. 

QPF PURERGBCOLOR Applies if you have requested an RGB 
value either by asking for a presentation parameter identitiy that 
specifies an RGB, such as PP_FOREGROUNDCOLOR, or by using one 
of the QPF_COLORINDEX flags. If you have asked for an RGB value, 
this flag causes this function to return the nearest nondithered 
(pure) RGB to the actual RGB value. A pure color is a color physi- 
cally available on the device. A dithered color is a simulation of an 
unavailable color that mixes two or more pure colors in a small re- 
peated pattern. 


RETURNS 


The count of bytes returned, or zero if no presentation parameters 
were assigned to the window, or if an error occurred. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINSYS 


SEE ALSO 


WinSetPresParam -307, WinRemovePresParam -300, 
WinInvalidateRect -138, WinBeginPaint -105, WinGetPS -108 
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NOTES 


Presentation parameters are identity value pairs that a window can use 
when displaying text and drawing its background. See WinSetPres- 
Param for the presentation parameter identities defined by PM. 

The user can specify presentation parameters to a window using 
the Scheme Palette, Font Palette, and Color Palette objects from the 
OS/2 Desktop (by default, these objects reside in the System Setup 
folder, which is in the OS/2 System folder). A program can add or 
change a window’s presentation parameters using WinSetPresParam. 
Whenever the user or a program changes a window’s presentation pa- 
rameter, PM stores the presentation parameters in the window data 
structure and passes the window WM_PRESPARAMCHANGED. A typi- 
cal response to this message is to invalidate the window to force a re- 
paint. Then the window can issue this function to retrieve the presen- 
tation parameters during the WM_PAINT message. 

You can specify up to two presentation parameters to search for, 
but this function returns only one, giving priority to the identifier in 
ulPPI. If you do not specify QPF_NOINHERIT in the flags, and if this 
function doesn’t find the presentation parameters defined on the win- 
dow specified by hwnd, it searches up the owner window hierarchy un- 
til it finds the presentation parameter or reaches the top of the tree. 

Apparently, WinBeginPaint and WinGetPS query the presentation 
parameter for font (PP_FONTNAMESIZE) and create a logical font and 
set it into the presentation space. Thus, a program using a cached- 
micro presentation space doesn’t need to query the font. However, 
programs that use micro or normal presentatation spaces that wish to 
react to presentation parameter font changes must use WinQuery- 
PresParam to retrieve the font name and size and then use 
GpiCreateLogFont and GpiSetCharSet to make the font the current 
one in the presentation space before drawing text. 


EXAMPLE 


This code fragment from a window procedure uses presentation para- 
meters for its foreground and background colors. Since it uses a 
cached-micro presentation space, it also responds to font changes (see 
preceding note). If there are no presentation parameters attached to 
the window or its ancestors up the owner tree, it querys the default sys- 
tem colors. 


case WM_SYSCOLORCHANGE : 


// repaint if system colors change (ALT drag from scheme palette) 
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WinInvalidateRect ( hwnd, NULL, TRUE ); 
return 0; 
case WM_PRESPARAMCHANGED: 
// repaint if presentation parameters change (drag from color or 
// font palettes) 
WinInvalidateRect ( hwnd, NULL, TRUE ); 
return 0; 
case WM_PAINT: 
{ 


BOOL fSuccess; // return from API 

LONG cb; // return from API 

RECT, rGls // invalid rectangle 

HPS hps; // cached-micro PS handle 


LONG 1ColorFore; // foreground color 
LONG 1ColorBack; // background color 
// query foreground color as presentation parameter 
// if none, use system-default foreground color 
cb = WinQueryPresParam ( hwnd 
, PP_FOREGROUNDCOLOR 
7% 
, NULL 
, sizeof ( LONG ) 
, &lColorFore 
y OTF 
if { cb == 0 j 
l1ColorFore = WinQuerySysColor ( HWND_DESKTOP 
, SYSCDR. OUTPUTTERT, © )¢ 
// query background color as presentation parameter 
// if none, use system-default background color 
cb = WinQueryPresParam ( hwnd 
, PP_BACKGROUNDCOLOR 
, O 
, NULL 
, sizeof ( LONG ) 
, &lColorBack 
, ONS 
Le { ee ea D>) 
1ColorBack = WinQuerySysColor ( HWND_DESKTOP 
, SYSCLR_WINDOW, O ); 
// retrieve a cached-micro PS 


GpiCreateLogColorTable ( hps, 0, LCOLF_RGB, 0, 0, NULL ); 
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WinFillRect ( hps, &rcl, l1ColorBack ); 
// set the foreground color 
GpiSetColor ( hps, l1ColorFore ); 


// draw text and graphics in foreground color 


WinEndPaint ( hps ); 
} 


return 0; 





WinQueryWindow 
Retrieves a window handle, given a related window’s handle. 


SYNTAX 
HWND WinQueryWindow(HWND hwndKnown, ULONG cmd) 


PARAMETERS 

hwndKnown - input 

The handle of a window. 

cmd - input 

One of the following commands: 


QW_BOTTOM Return the input window’s child that is lowest in the 
Z-order. 

QW_FRAMEOWNER If hwndKnown refers to a frame window, return 
the frame’s owner, otherwise return NULLHANDLE. 

QW_NEXT Return the input window's next sibling (below in the 
stack of siblings). You can pass the returned window handle to an- 
other call to this function in a loop to enumerate all of the siblings 
below the input window in the stack of siblings. 

QW_NEXTTOP Cycles through the all nonminimized visible top- 
level frame windows. 

QW_OWNER Return the input window’s owner. 

QW_PARENT Return the input window’s parent. 

QW_PREV_ Return the input window’s previous sibling (above in the 
stack of siblings). You can pass the returned window handle to an- 
other call to this function in a loop to enumerate all of the siblings 
above the input window in the stack of siblings. 
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QW_PREVTOP Cycles through the all nonminimized visible top- 
level frame windows in reverse order. 

QW_TOP Return the input window's child that is highest in the Z- 
order. 


RETURNS 


The related window handle, or NULLHANDLE if none exists or an er- 
ror occurred. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR INVALID_ 0x1303 - PMERR_ INVALID _ 
HWND PARM 
OTHER INFO 


Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinWindowFromID -322, WinGetNextWindow -278, 
WinSetParent -306, WinSetOwner -305 


NOTES 


If you call this function so that it returns the desktop or object window's 
handle, it will not match the HWND_DESKTOP or HWND_ OBJECT 
symbols defined in PMWIN.H, but it will match the values returned 
by WinQueryDesktopWindow (pg 331) or WinQueryObjectWindow 
(pg 332). 





@ WinQueryWindowPos 


Retrieves a window’s size and position. 


SYNTAX 
BOOL WinQueryWindowPos(HWND hwnd, PSWP pswp) 


PARAMETERS 

hwnd - input 

The handle of the window to query. 
pswp - output 


Pass the address of an SWP structure that this function fills in: 
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typedef struct _SWP /* swp */ 
{ 
ULONG f1; 
LONG cy; 
LONG cx; 
LONG y; 
LONG xX; 
HWND hwndInsertBehind; 
HWND hwnd; 
ULONG ulReserved1; 
ULONG ulReserved2; 
} SWP; 


fl A combination of SWP flags that you can use in a call to Win- 
SetWindowPos, which reflect the current state of the window. In 
other words, if you call WinSetWindowPos with these returned flags, 
it will position and size the window to its current size and position. 
See WinSetWindowPos for a description of the flags. 

cy The window's height in pixels. 

cx The window’s width in pixels. 

y The window's y-coordinate in pixels, relative to its parent’s lower 
left. 

x The window's x-coordinate in pixels, relative to its parent’s lower 
left. 

hwndInsertBehind ‘The window’s sibling immediately on top of it in 
the stack of windows. 

hwnd The window's handle. This field is used by the WinSetMult- 
WindowPos function which uses this same structure. 

ulReservedl Reserved. 

ulReserved2 Reserved. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_ Oxl019 - PMERR_INVALID_ 
HWND FLAG 
OTHER INFO 


Include file: pmwin.h Define: INCL_WINWINDOWMGR 
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SEE ALSO 


WinSetWindowPos -311, WinSetMultWindowPos -303, 
WinQueryWindowRect -294 





@ WinQueryWindowProcess 


Retrieves a window’s process and thread identifiers. 


SYNTAX 

BOOL WinQueryWindowProcess(HWND hwnd, PPID ppid, PTID 
ptid) 

PARAMETERS 

hwnd - input 


The handle of the window to query. 

ppid - output 

Pass the address of a PJD that this function fills in with the window's 
process identifier. A PD is an unsigned long. 

ptid - output 

Pass the address of a TID that this function fills in with the window’s 
thread identifier. A T/D is an unsigned long. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


None 


NOTES 


This function returns the process and thread identifiers of the process 
and thread that created the window. 
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This function is useful in dynamic data exchange (DDE), where a 
DDE participant needs to allocate memory shareable with another 
window's process. The DDE participant will receive its conversation 
partner’s window handle and use this function to retrieve the partner’s 
process identifier to use as an input to DosGiveSharedMem. 





WinQueryWindowPtr 


Retrieves a pointer from the window data structure. 


SYNTAX 
PVOID WinQueryWindowPtr (HWND hwnd, ULONG index) 


PARAMETERS 

hwnd - input 

The handle of the window to query. 

index - input 

You can use this function to retrieve a pointer from either the system- 
defined area or the application-defined area. To query the system- 
defined area: 


QWP_PFNWP Retrieve the window’s window procedure address. 

To query the application-defined area, pass the zero-based byte index 
of the pointer to retrieve. You can use the symbol QWL_USER defined 
in PMWIN.H for 32-bit values at index zero. 


RETURNS 


The pointer value, or zero if an error occurred. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 
0x1003 - PMERR_PARAMETER_ OUT_OF_RANGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinSetWindowPtr -314, WinQueryWindowULong -296, 
WinQueryWindowUShort -298, WinRegisterClass -28 
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NOTES 


To set or retrieve pointers in the application-defined area, you must re- 
serve application-defined space in the window data structure in 
WinRegisterClass. If you do not allocate enough storage, this function 
returns zero and WinGetLastError returns PMERR_PARAMETER_ 
OUT_OF_RANGE. 





@ WinQueryWindowRect 


Retrieves the rectangle containing the window's coordinates. 


SYNTAX 
BOOL WinQueryWindowRect(HWND hwnd, PRECTL prcl) 


PARAMETERS 

hwnd - input 

The handle of the window to query. 

prel - output 

Pass the address of a RECTL structure that this function fills in. 


RETURNS: 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinQueryWindowPos -290, WinSetWindowPos -311 


NOTES 


This function returns a rectangle that contains the coordinates of the 
window in pixels. This function sets the xLeft and yBotiom fields to zero 
and sets the xRight and yTop fields to the window’s width (- 1) and 
height (- 1) respectively. 
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@® WinQueryWindowText 


Retrieves a window’s text string. 


SYNTAX 
LONG WinQueryWindowText(HWND hwnd, LONG cb, PCHAR ach) 


PARAMETERS 

hwnd - input 

The handle of the window to query. 

cb - input 

The size of the character array passed in the next argument. 

ach - output 

Pass the address of a character array that this function fills in with the 
window’s text, truncating it if necessary. This function always null- 
terminates the returned string. 


RETURNS 
The number of characters returned, or zero if an error occurred. 


Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinSetWindowText -315, WinQueryWindowTextLength -296, 
WinQueryWindowProcess -292 


NOTES 


This function sends the WM_QUERYWINDOWPARAMS message to the 
window. Some windows do not respond to this message and thus do 
not return any text. If you send this message to a frame window, it re- 
turns the text of any titlebar child window. 

Before issuing this function, you can call WinQueryWindowText- 
Length and use the returned text length to allocate the character array. 
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If you call this function on a window in another process, you must 
allocate the ach argument in storage accessible to the other process, 
for example using DosAllocSharedMem and DosGiveSharedMem. 





@ WinQueryWindowTextLength 


Retrieves the number of characters in a window’s text string. 


SYNTAX 
LONG WinQueryWindowTextLength (HWND hwnd) 


PARAMETERS 

hwnd - input 

The handle of the window to query. 
RETURNS 


The window text length, excluding the null terminator, or zero if an er- 
ror occurred. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinSetWindowText -315, WinQueryWindowText -295 


NOTES 


This function sends the WM_QUERYWINDOWPARAMS message to the 
window. 





@ WinQueryWindowULong 


Retrieves a 32-bit value from the window data structure. 


SYNTAX: 
ULONG WinQueryWindowULong(HWND hwnd, LONG index) 
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PARAMETERS 

hwnd - input 

The handle of the window to query. 

index - input 

You can use this function to retrieve a 32-bit value from either the sys- 
tem-defined area or the application-defined area. To query the system- 
defined area, use one of the following: 


QWL_HMOQ Retrieve the window’s message queue handle. 

QWL_PENDATA Reserved 32-bit field for operating system exten- 
sions. 

QWL_RESERVED Reserved 32-bit field. 

QWL_STYLE Retrieve the window’s style bit flags, which consist of 
CS_ flags (such as CS_SIZEREDRAW), WS_ flags (such as WS_VISI- 
BLE) and any window class-defined styles (such as BS_AUTORA- 
DIOBUTTON). 

QWP_PFNWP Retrieve the window’s window procedure address. 
You can also retrieve this with WinQueryWindowPtr. 


See below for a description of frame window indexes. 

To query the application-defined area, pass the zero-based byte index 
of the 32-bit value to retrieve. You can use the symbol QWL_USER de- 
fined in PMWIN.H for 32-bit values at index zero. 


RETURNS 
The 32-bit value, or zero if an error occurred. 


Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 
0x1003 - PMERR_PARAMETER_ OUT_OF_RANGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinSetWindowULong -316, WinQueryWindowPtr -293, 
WinQueryWindowUShort -298, WinRegisterClass -28 


NOTES 


To set or retrieve pointers in the application-defined area, you must re- 
serve application-defined space in the window data structure in 
WinRegisterClass. If you do not allocate enough storage, this function 
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returns zero and WinGetLastError returns PMERR_PARAMETER_ 
OUT_OF_RANGE. 

If hwnd refers to a frame window, you can specify the following in- 
dexes in the application-defined area for the frame window class: 


QWL_HHEAP Retrieve the frame window’s memory heap handle. 

QWL_HWNDFOCUSSAVE Retrieve the handle of the last child win- 
dow that had input focus. 

QWL_DEFBUTTON If the frame window is a dialog, returns the 
identifier of the dialog’s default pushbutton. 

QWL_PSSCBLK Not documented. 

QWL_PFEPBLK Not documented. 

QWL_PSTATBLK Not documented. 





@ WinQueryWindowUShort 


Retrieves a 16-bit value from the window data structure. 


SYNTAX 
USHORT WinQueryWindowUShort(HWND hwnd, LONG index) 


PARAMETERS 

hwnd - input 

The handle of the window to query. 

index - input 

You can use this function to retrieve a 16-bit value from either the sys- 
tem-defined area or the application-defined area. To query the system- 
defined area, use: 

QWS_ID Retrieve the window's identifier. 

See below for a description of frame window indexes. 

To query the application-defined area, pass the zero-based byte index 
of the pointer to retrieve. You can use the symbol QWL_USER defined 
in PMWIN.H for 16-bit values at index zero. 


RETURNS 


The 16-bit value, or zero if an error occurred. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 
0x1003 - PMERR_PARAMETER_OUT_OF_RANGE 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinSetWindowUShort -317, WinQueryWindowPtr -293, 
WinQueryWindowULong -296, WinRegisterClass -28, 
WinFlash Window -87, WinDismissDlg -174 


NOTES 


To set or retrieve pointers in the application-defined area, you must re- 
serve application-defined space in the window data structure in Win- 
RegisterClass. If you do not allocate enough storage, this function re- 
turns zero and WinGetLastError returns PMERR_PARAMETER_OUT_ 
OF_RANGE. 

If hwnd refers to a frame window, you can specify the following in- 
dexes in the application-defined area for the frame window class: 


OWS_CXRESTORE Retrieve the window's width (in pixels) when 
restored. 

QWS_CYRESTORE Retrieve the window’s height (in pixels) when 
restored. 

QWS_FLAGS Retrieve the window’s frame flags, which are a combi- 
nation of the following flags: 
FF ACTIVE The frame is active. 
FF _ DLGDISMISSED The frame is a dialog box that has been hid- 

den with WinDismissDlg. 
FF_ FLASHHILITE ‘The frame is flashing (see WinFlashWindow) 
and currently highlighted. 

FF_FLASHWINDOW the frame is flashing (see WinFlashWindow). 
FF_ OWNERDISABLED The frame’s owner is disabled. 
FF OWNERHIDDEN The frame’s owner is hidden. 
FF SELECTED The frame is selected. 

QWS_RESULT Retrieve the result of WinDismissDle. 

QWS_XMINIMIZE Retrieve the x-coordinate (in pixels) of the win- 
dow’s minimized position. PM initializes this to -1, which indicates 
that the window has not yet been minimized. 

QWS_XRESTORE Retrieve the x-coordinate (in pixels) of the win- 
dow’s restored position. 
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QWS_YMINIMIZE Retrieve the y-coordinate (in pixels) of the win- 
dow’s minimized position. PM initializes this to -1, which indicates 
that the window has not yet been minimized. 

QWS_YRESTORE Retrieve the y-coordinate (in pixels) of the win- 
dow’s restored position. 





@ WinRemovePresParam 





Deletes a presentation parameter from a window. 


SYNTAX 
BOOL WinRemovePresParam (HWND hwnd, ULONG 7d) 


PARAMETERS 

hwnd - input 

The window from which to remove the presentation parameters. 

id - input 

The identifier of the presentation parameter to remove. See WinSet- 
PresParam for a listing of presentation parameter identifiers. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINSYS 


SEE ALSO 
WinSetPresParam -307, WinQueryPresParam -285 


NOTES 


Presentation parameters are identity value pairs that a window can use 
when displaying text and drawing its background. See WinSetPres- 
Param for the presentation parameter identities defined by PM. 

The user can specify presentation parameters to a window using 
the Scheme Palette, Font Palette, and Color Palette objects from the 
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OS/2 Desktop (by default, these objects reside in the System Setup 
folder, which is in the OS/2 System folder). A program can add or 
change a window's presentation parameters using WinSetPresParam, 
or delete them with this function. Whenever the user or a program 
changes a window's presentation parameter, PM stores the presenta- 
tion parameters in the window data structure and passes the window 
WM_PRESPARAMCHANGED. 





WinRestoreWindowPos 





Restores a window’s size, position, and flags from a profile. 


SYNTAX 

BOOL WinRestoreWindowPos(PSZ pszAppname, PSZ pszKeyname, 
HWNDh;wnd) 

PARAMETERS 


pszAppname - input 

The application name string that the system will use to retrieve the 
size, position, and flags from the profile. 

pszKeyname - input 

The keyname string that the system will use to retrieve the size, posi- 
tion, and flags from the profile. 

hwnd - input 

The handle of the window whose size, position, and flags should be re- 
trieved. This is normally a frame window. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwp.h Define: INCL_WORKPLACE 


SEE ALSO 
WinStoreWindowPos -301 
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NOTES 


This function attempts to read a window’s positional information from 
the OS2.INI file under the specified application, keyname, and win- 
dow handle. For succesful completion, the data must have been previ- 
ously saved with WinStoreWindowPos. This function will also restore 
any presentation parameters saved by WinStoreWindowPos. 





@® WinSaveWindowPos 





Lets a frame window save an array of window position structures. 


SYNTAX 

BOOL WinSaveWindowPos(HSAVEWP hsuvwp, PSWP pswp, ULONG 
cswp) 

PARAMETERS 

hsvwp - input 


Handle to frame window positioning process. Normally provided by 
the second message parameter of WM_ADJUSTFRAMEPOS. 
pswp - input 


Pass the address of an array of SWP structures: 


typedef struct _SWP /* swp */ 
{ 


ULONG f1; 
LONG Cy; 
LONG Cx; 
LONG Vy; 
LONG xy 


HWND hwndInsertBehind; 
HWND hwnd; 
ULONG ulReservedl; 
ULONG ulReserved2; 

} SWP; 


fl A combination of SWP flags. See WinSetWindowPos for a descrip- 
tion of the flags. 

cy The window’s height in pixels. 

cx The window's width in pixels. 
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y The window’s y-coordinate in pixels, relative to its parent’s lower 
left, 

x The window’s x-coordinate in pixels, relative to its parent’s lower 
left. 

hwndInsertBehind The window's sibling immediately on top of it in 
the stack of windows. 

hwnd The window's handle. 

ulReservedl Reserved. 

ulReserved2 Reserved. 

cswp - input 


The number of SWP structures in the array. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_ INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINFRAMEMGR 





WinSetMultWindowPos 





Sets several windows’ size, position, flags, and Z-order. 


SYNTAX 
BOOL WinSetMultWindowPos(HAB hab, PSWP pswp, ULONG cswp) 


PARAMETERS 

hab - input 

Anchor block handle. 

pswp - input 

Pass the address of an array of SWP structures, one for each window 
you wish to affect: 


typedef struct _SWP /* swp */ 
{ 

ULONG f1; 

LONG cy? 
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LONG cx: 
LONG Vr 
LONG x: 


HWND hwndInsertBehind; 
HWND hwnd; 
ULONG ulReserved1; 
ULONG ulReserved2; 

} SWP; 


fl A combination of SWP flags. See WinSetWindowPos for a descrip- 
tion of the flags. 

cy The window's height in pixels. 

cx The window's width in pixels. 

y The window's y-coordinate in pixels, relative to its parent’s lower 
left. 

x The window's x-coordinate in pixels, relative to its parent’s lower 
left. 

hwndInsertBehind The window’s sibling immediately on top of it in 
the stack of windows. 

hwnd The window's handle. 

ulReservedl Reserved. 

ulReserved2 Reserved. 


cswp - input 
The number of SWP structures in the array. 
RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinSetWindowPos -311, WinQueryWindowPos -290, 
WinSave WindowPos -302, WinRestoreWindowPos -301, 
WinGetMaxPosition -275, WinGetMinPosition -277 


NOTES 
All of the windows affected by this call must have the same parent. 
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@ WinSetOwner 





Changes a window’s owner window. 


SYNTAX 
BOOL WinSetOwner(HWND hwnd, HWND hwndOwner) 


PARAMETERS 

hwnd - input 

The handle of the window for which to change the owner. 
hwndOwner - input 

The new owner window’s handle or NULLHANDLE. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinQueryWindow -289, WinSetParent -306 


NOTES 


Owned windows have the following characteristics: 


@ PM destroys the owned window when the owner is destroyed. 

@ If the owned window is a frame (standard window, dialog, or mes- 
sage box), it will not go “behind” its owner in the stack of windows. 

@ By convention, owned windows pass notification messages to their 
owner. For example, a pushbutton passes WM_COMMAND to its 
owner when the user clicks the button. 


You can query the current owner window with WinQueryWindow, 
QW_OWNER. 
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@ WinSetParent 





Changes a window’s parent window. 


SYNTAX 
BOOL WinSetParent(HWND hwnd, HWND hwndParent, BOOL /) 


PARAMETERS 

hwnd - input 

The handle of the window for which to change the parent. 
hwndParent - input 

The new parent window’s handle or NULLHANDLE. You can pass 
HWND_DESKTOP to make the window a top-level window, or HWND_ 
OBJECT to make the window invisible. 


f- input 
Pass TRUE to force a repaint on the old and new parent windows, 
FALSE otherwise. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Oxl001 - PMERR_ INVALID _HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinQueryWindow -289, WinSetOwner -305 


NOTES 


You can change a child window’s parent with this function and retrieve 
the parent handle with WinQueryWindow, QW_PARENT: 
A child window has the following characteristics: 


@ PM destroys the child window when the parent is destroyed. 

@ PM clips the child window’s output to the parent window's 
boundary. 

® A child window's coordinate origin is relative to its parent’s. 
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@ WinSetPresParam 





Assigns a presentation parameter to a window. 


SYNTAX 
BOOL WinSetPresParam(HWND hwnd, ULONG id, ULONG cd, 
PVOID pPresParm) 
PARAMETERS 
hwnd - input 
The handle of the window to which to attach the presentation para- 
meter. 
id - input 
The presentation parameter identifier, which is one of the following: 
Length in 
identifier Value Bytes 
PP_ACTIVECOLOR RGB 4 
PP_ACTIVECOLORINDEX color index 4 
PP_ACTIVETEXTBGNDCOLOR RGB 4 
PP_ACTIVETEXTBGNDCOLORINDEX color index 4. 
PP_ACTIVETEXTFGNDCOLOR RGB 4 
PP_ACTIVETEXTFGNDCOLORINDEX color index 4 
PP_BACKGROUNDCOLOR RGB 4 
PP_BACKGROUNDCOLORINDEX color index 4 
PP_BORDERCOLOR RGB a 
PP_BORDERCOLORINDEX color index 4 
PP_DISABLEDBACKGROUNDCOLOR RGB 4 
PP_DISABLEDBACKGROUNDCOLORINDEX _ color index 4 
PP_DISABLEDFOREGROUNDCOLOR RGB + 
PP_DISABLEDFOREGROUNDCOLORINDEX color index + 
PP_FONTHANDLE logical font ID from 4 


GpiCreateLogFont 
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PP_FONTNAMESIZE string of form “xx.nnnn” where length 
XX 1S point size, nnnn is font of 


face name string 


PP_FOREGROUNDCOLOR 
PP_FOREGROUNDCOLORINDEX 
PP_HILITEBACKGROUNDCOLOR 
PP_HILITEBACKGROUNDCOLORINDEX 
PP_HILITEFOREGROUNDCOLOR 
PP_HILITEFOREGROUNDCOLORINDEX 
PP_INACTIVECOLOR 
PP_INACTIVECOLORINDEX 
PP_INACTIVETEXTBGNDCOLOR 
PP_INACTIVETEXTBGNDCOLORINDEX 
PP_INACTIVETEXTFGNDCOLOR 
PP_INACTIVETEXTFGNDCOLORINDEX 
PP_MENUBACKGROUNDCOLOR 
PP_MENUBACKGROUNDCOLORINDEX 
PP_MENUDISABLEDBGNDCOLOR 
PP_MENUDISABLEDBGNDCOLORINDEX 
PP_MENUDISABLEDFGNDCOLOR 
PP_MENUDISABLEDFGNDCOLORINDEX 
PP_MENUFOREGROUNDCOLOR 
PP_MENUFOREGROUNDCOLORINDEX 
PP_MENUHILITEBGNDCOLOR 
PP_MENUHILITEBGNDCOLORINDEX 
PP_MENUHILITEFGNDCOLOR 
PP_MENUHILITEFGNDCOLORINDEX 
PP_SHADOW 


RGB 
color index 
RGB 
color index 
RGB 
color index 
RGB 
color index 
RGB 
color index 
RGB 
color index 
RGB 
color index 
RGB 
color index 
RGB 
color index 
RGB 
color index 
RGB 
color index 
RGB 
color index 


RGB 


Se eo 
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cb - input 

The length of the presentation parameter value. See the preceding 
table. 

pPresParm - input 

Pass the address of the presentation parameter value. See the preced- 
ing table and the Notes for more information. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_ INVALID _HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinRemovePresParam -300, WinQueryPresParam -285 


NOTES 


Presentation parameters are identity value pairs that a window can use 
when displaying text and drawing its background. 

Most presentatation parameters involve color and let you specify 
color as a color index or as an RGB value. Color indexes, such as 
CLR_BLUE (see PMGPI.H), are indexes into a presentation space’s 
logical color table. The default color table has only 16 entries, so color 
indexes are not as flexible as the RGB model, which lets you specify any 
of 16.7 million colors. 

The RGB model represents a color in 8-bit intensities of red, 
green, and blue, stored in an a 32-bit number. You can define the fol- 
lowing macro to specify an RGB value to pass to this function: 


#define MAKERGB(r,g,b) ((LONG)r | ((LONG)g<<8) | ((LONG)b<<16) ) 
LONG 1ColorBack = MAKERGB (0, 100, 200); 
fSuccess = WinSetPresParam (hwndChild, PP_BACKGROUNDCOLOR 

, sizeof (long), &lColorBack ); 


The user can specify presentation parameters to a window using 
the Scheme Palette, Font Palette, and Color Palette objects from the 
OS/2 Desktop (by default, these objects reside in the System Setup 
folder, which is in the OS/2 System folder). A program can add or 
change a window's presentation parameters using this function. 
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Whenever the user or a program changes a window's presentation pa- 
rameter, PM stores the presentation parameters in the window data 
structure and passes the window WM_PRESPARAMCHANGED. A typi- 
cal response to this message is to invalidate the window to force a re- 
paint. Then the window can issue WinQueryPresParam to retrieve the 
presentation parameters during the WM_PAINT message. 

Since index mode is the default, before the recipient window can 
call GpiSetColor to set an RGB color value, it must first set the presen- 
tation space into RGB mode with: 


GpiCreateLosColorTable (hps, 0, LCOLF_RGB, 0, 0, NULL ); 





WinSetWindowBits 





Sets bit flags into the window data structure. 


SYNTAX 

BOOL WinSetWindowBits(HWND hwnd, LONG index, ULONG 
[lData, ULONG /lMask) 

PARAMETERS 

hwnd - input 

The handle of the window in which to set the bits. 

index - input 


You can use this function to set bits in a 32-bit value from either the sys- 
tem-defined area or the application-defined area. To set into the sys- 
tem-defined area, use: 


QWL_STYLE Set bits in the window’s style bit flags, which consist of 
CS_ flags (such as CS_SIZEREDRAW), WS_ flags (such as WS_VISI- 
BLE), and any window-class defined styles (such as BS_AUTORA- 
DIOBUTTON). 


To set into the application-defined area, pass the zero-based byte 
index of the 32-bit value in which to set bits. You can use the symbol 
QWL_USER defined in PMWIN.H for 32-bit values at index zero. 
fiData - input 
The bit flags to set or clear in the window data structure. 
flMask - input 
A mask that specifies which bits to modify in the window data struc- 
ture. Set a bit position to zero for that bit to be left alone. Set a bit po- 
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sition to one to modify the bit as specified by the corresponding bit in 
the flData argument. 


RETURNS 
TRUE if successful, FALSE otherwise. 


Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID HWND 
0x1003 - PMERR_ PARAMETER OUT_OF_RANGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinSetWindowULong -316, WinQueryWindowPtr -293, 
WinQueryWindowUShort -298, WinRegisterClass -28 


NOTES 


To modify the application-defined area, you must reserve application- 
defined space in the window data structure in WinRegisterClass. If you 
do not allocate enough storage, this function returns zero and Win- 
GetLastError returns PMERR_PARAMETER_OUT_OF_RANGE. 





WinSetWindowPos 





Sets a window’s size, position, flags, and Z-order. 


SYNTAX 


BOOL WinSetWindowPos(HWND hwnd, HWND hwndBehind, 
LONG x, LONG y, LONG cx, LONG oy, 
ULONG /l) 


PARAMETERS 

hwnd - input 

The handle of the window to modify. 

hwndBehind - input 

The handle of the sibling window that hwnd should be placed behind 


in the stack of windows. This argument is ignored unless you specify 
SWP_ZORDER in the flags (pass NULLHANDLE). You can pass 
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HWND_TOP or HWND_BOTTOM to move the window to the top or 

bottom of its siblings. 

x - input 

The new x-coordinate, in pixels. This argument is ignored unless you 

specify SWP_MOVE in the flags. 

y - input 

The new y-coordinate, in pixels. This argument is ignored unless you 

specify SWP_MOVE in the flags. 

cx - input 

The new window width in pixels. This argument is ignored unless you 

specify SWP_S/ZE in the flags. 

cy - input 

The new window height in pixels. ‘This argument is ignored unless you 

specify SWP_S/ZE in the flags. 

fl- input 

A combination of the following flags: 

SWP_ACTIVATE Make the window the active frame window. 

SWP_DEACTIVATE Deactivate the frame window. 

SWP_EXTSTATECHANGE Not documented. 

SWP_FOCUSACTIVATE Not documented. 

SWP_FOCUSDEACTIVATE Not documented. 

SWP_HIDE Make the window invisible by clearing its WS_VISJBLE 
flag. 

SWP_MAXIMIZE Maximize the frame window. Cannot be used with 
SWP_RESTORE or SWP_MINIMIZE. 

SWP_MINIMIZE Minimize the frame window. Cannot be used with 
SWP_RESTORE or SWP_MAXIMIZE. 

SWP_ MOVE Move the window. 

SWP_NOADJUST Do not send the WM_ADJUSTWINDOWPOS mes- 
sage. 

SWP_NOREDRAW Do not invalidate the window. 

SWP_RESTORE Restore a minimized frame window. Cannot be 
used with SWP_MAXIMIZE or SWP_MINIMIZE. 

SWP_SHOW Make the window invisible by setting its WS_VISIBLE bit. 

SWP_SIZE Change the window's size. 

SWP_ZORDER Change the window’s position in relation to its sib- 
ling windows. 
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RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_ 0x1019 - PMERR_INVALID_ 
HWND FLAG 
OTHER INFO 


Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinQueryWindowPos -290, WinQueryWindowRect -294, 
WinSetMultWindowPos -303 


NOTES 


This function lets a program change a window's size, position, z-order, 
or visible flag. 

If you issue this function with SW_SIZE or SWP_MOVE on a frame 
window, by default, the frame will modify the requested size and posi- 
tion to align itself on the screen for best performance. To prevent this, 
create the frame window with the FCF_NOBYTEALIGN frame creation 
flag. Similarly, listbox windows, by default, modify their height so an in- 
tegral number of rows are visible. You can defeat this behavior by cre- 
ating the listbox with the LS_NOADJUSTPOS style. 

During its operation, this function sends the window the following 
messages: 


WM_ADJUSTWINDOWPOS Sent unless you specify SWP_NOAD- 
JUSTPOS, this message passes the window the proposed window size 
and position, and lets the window modify it. 

WM_CALCVALIDRECTS Sent if the window’s size changed to let 
PM calculcate how much of the window’s bitmap is still valid. 

WM_ACTIVATE Sent if the frame window was activated or deacti- 
vated. 

WM_SIZE Sent if the window’s size changed. 

WM_SHOW Sent if the window’s visible flag changed. 

WM_MOVE Sent if the window’s position changed and the window 
class was registered with the CS_MOVENOTIFY class style. 
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@® WinSetWindowPtr 





Sets a 32-bit value into the window data structure. 


SYNTAX 
BOOL WinSetWindowPtr(HWND hwnd, LONG index, PVOID p) 


PARAMETERS 

hwnd - input 

The handle of the window in which to set the pointer. 

index - input 

You can use this function to set a pointer into either the system-defined 
area or the application-defined area. To set the system-defined area: 


QWP_PFNWP _ Set the window’s window procedure address. 

To set into the application-defined area, pass the zero-based byte index 
of the pointer to set. You can use the symbol QWL_USER defined in 
PMWIN.H for 32-bit values at index zero. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID HWND 
0x1003 - PMERR_ PARAMETER OUT_OF_ RANGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinQueryWindowPtr -293, WinSetWindowULong -316, 
WinQueryWindowUShort -298, WinRegisterClass -28, 
WinSubclassWindow -321 


NOTES 


To set or retrieve pointers in the application-defined area, you must re- 
serve application-defined space in the window data structure in 
WinRegisterClass. If you do not allocate enough storage, this function 
returns zero and WinGetLastError returns PMERR_PARAMETER_ 
OUT_OF_RANGE. 
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You can also change a window’s procedure address with Win- 
SubclassWindow. 





WinSetWindow Text 


Assigns a window's text string. 


SYNTAX 
BOOL WinSetWindowText(HWND hwnd, PSZ psz) 


PARAMETERS 

hwnd - input 

The handle of the window to modify. 

psz - input 

Pass the address of the null-terminated text string to assign. 


RETURNS 
TRUE if succesful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinQueryWindowText -295 


NOTES 


This function sends the WM_SETWINDOWPARAMS message to the tar- 
get window, passing the address string. It is up to the destination win- 
dow to process this message and interpret the text. Some windows ig- 
nore this message and thus will ignore this function. 

If you send this message to a frame window, it sets the text in any 
child title bar window. 

If you send this message to a button, the button class interprets a 
tilde (~) in the string as defining a character mnemonic. 
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@® WinSetWindowULong 


Sets a 32-bit value into the window data structure. 


SYNTAX 

BOOL WinSetWindowULong (HWND hwnd, LONG index, 
ULONG ul) 

PARAMETERS 

hwnd - input 


The handle of the window in which to set the 32-bit value. 

index - input 

You can use this function to set a 32-bit value into either the system- 
defined area or the application-defined area. To set the system-defined 
area, use one of the following: 


QWL_HMQ Set the window’s message queue handle. 

QWL_PENDATA Reserved 32-bit field for operating system exten- 
sions. 

QWL_RESERVED Reserved 32-bit field. 

QWL_STYLE Set the window’s style bit flags, which consist of CS_ 
flags (such as CS_SIZEREDRAW), WS_ flags (such as WS_VISIBLE), 
and any window-class defined styles (such as BS_AUTORADIOBUT- 
TON). Note that you can also use WinSetWindowBits to modify this 
field. 

QWP_PFNWP Set the window's window procedure address. You can 
also set this with WinQueryWindowPtr. 


See Notes for a description of frame window indexes. 

‘To set into the application-defined area, pass the zero-based byte index 
of the 32-bit value to retrieve. You can use the symbol QWL_USER de- 
fined in PMWIN.H for 32-bit values at index zero. 

ul - input 

The 32-bit value to set into the window data structure. 


RETURNS 
TRUE if succesful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR INVALID HWND 
0x1003 - PMERR_ PARAMETER OUT_OF_RANGE 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinQueryWindowULong -296, WinSetWindowPtr -314, 
WinSetWindowUShort -317, WinSetWindowBits -310 
WinRegisterClass -28 


NOTES 


To set or retrieve pointers in the application-defined area, you must re- 
serve application-defined space in the window data structure in 
WinkegisterClass. If you do not allocate enough storage, this function 
returns FALSE, and WinGetLastError returns PMERR_PARAMETER._ 
OUT_OF_RANGE. 

If hwnd refers to a frame window, you can specify the following in- 
dexes in the application-defined area for the frame window class: 


QWL_HHEAP _ Set the frame window’s memory heap handle. 

QWL_HWNDFOCUSSAVE Set the handle of the last child window 
that had input focus. 

QWL_DEFBUTTON If the frame window is a dialog, sets the identi- 
fier of the dialog’s default pushbutton. 

QWL_PSSCBLK Not documented. 

QWL_PFEPBLK Not documented. 

QWL_PSTATBLK Not documented. 





WinSetWindowUShort 





Sets a 16-bit value into the window data structure. 


SYNTAX 

BOOL WinSetWindowUShort(HWND hwnd, LONG index, 
USHORT us) 

PARAMETERS 

hwnd - input 


The handle of the window in which to set the 32-bit value. 
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index - input 

You can use this function to set a 16-bit value from either the system- 
defined area or the application-defined area. To set the system-defined 
area, use: 


QOWS_ID Set the window’s identifier. 


See Notes for a description of frame window indexes. 

To set into the application-defined area, pass the zero-based byte index 
of the pointer to retrieve. You can use the symbol QWL_USER defined 
in PMWIN.H for 16-bit values at index zero. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 
0x1003 - PMERR_PARAMETER OUT_OF_RANGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinQueryWindowUShort -298, WinSetWindowPtr -314, 
WinSetWindowULong -316, WinRegisterClass -28, 
WinFlashWindow -87, WinDismissDlg -174 


NOTES 


To set or retrieve pointers in the application-defined area, you must re- 
serve application-defined space in the window data structure in 
WinRegisterClass. If you do not allocate enough storage, this function 
returns zero, and WinGetLastError returns PMERR_PARAMETER_ 
OUT_OF_RANGE. 

If hwnd refers to a frame window, you can specify the following in- 
dexes in the application-defined area for the frame window class: 


QOWS_CXRESTORE Set the window’s width (in pixels) when re- 
stored. 

QWS_CYRESTORE Set the window’s height (in pixels) when re- 
stored. 

QWS_FLAGS | Set the window’s frame flags, which are a combination 
of the following flags: 
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FF ACTIVE The frame is active. 

FF_DLGDISMISSED The frame is a dialog box that has been hid- 
den with WinDismissDlg. 

FF_FLASHHILITE ‘The frame is flashing (see WinFlashWindow) 
and currently highlighted. 

FF FLASHWINDOW the frame is flashing (see WinFlashWindow). 

FF OWNERDISABLED The frame’s owner is disabled. 

FF_ OWNERHIDDEN The frame’s owner is hidden. 

FF SELECTED ‘The frame is selected. 

QWS_RESULT Set the result of WinDismissDlg. 

QWS_XMINIMIZE Set the x-coordinate (in pixels) of the window’s 
minimized position. PM initializes this to —1, which indicates that 
the window has not yet been minimized. 

QWS_XRESTORE Set the x-coordinate (in pixels) of the window’s 
restored position. 

QWS_YMINIMIZE Set the y-coordinate (in pixels) of the window’s 
minimized position. PM initializes this to -1, which indicates that 
the window has not yet been minimized. 

QWS_YRESTORE Set the y-coordinate (in pixels) of the window’s 
restored position. 





WinShowWindow 





Sets or clears the window's visible flag. 


SYNTAX 
BOOL WinShowWindow(HWND hwnd, BOOL f) 


PARAMETERS 

hwnd - input 

The handle of the window to show or hide. 

f- input 

Pass TRUE to show the window, FALSE to hide it. 
RETURNS 

TRUE if successful, FALSE otherwise. 

Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinEnableWindowUpdate -86, WinQueryWindowULong -296, 
WinSetWindowULong -316, WinIsWindowVisible -281 


NOTES 


This function sets or clears the window’s WS_VISIBLE flag, which is 
stored in the QWL_STYLE field in the window’s data structure. Note 
that even if this flag is on, the user might not be able to see the window 
because: 


@ The window is obscured by other windows. 

@ One of the window’s ancestors isn’t visible. 

@ One of the window’s ancestors is a descendant of HWND_OBJECT. 
@ The window’s size and position make it invisible (width of zero). 


If this function changes the window’s WS_VISIBLE flag, it sends 
the window the WM_SHOW message. 

This function is essentially the same as WinEnableWindow- 
Update, in that it sets or clears the window’s internal WS_VISIBLE style 
flag. The functions differ in that WinEnableWindowUpdate does not 
hide a window nor show it; it simply prevents the window’s output from 
being passed to the window. 





@ WinStoreWindowPos 





Saves a window’s size, position, and flags to a profile. 


SYNTAX 

BOOL WinStoreWindowPos(PSZ pszAppname, PSZ pszKeyname, 
HWND hwnd) 

PARAMETERS 


pszAppname - input 
The application name string that the system will use to write the size, 
position, and flags to the profile. 
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pszKeyname - input 

The keyname string that the system will use to write the size, position 
and flags to the profile. 

hwnd - input 

The handle of the window whose size, position, and flags should be 
saved. This is normally a frame window. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwp.h Define: INCL_WORKPLACE 


SEE ALSO 
WinRestoreWindowPos -301 


NOTES 


This function writes a window's positional information to the OS2.INI 
file under the specified application, keyname, and window handle. A 
program typically calls this function when the user closes the window, 
and calls WinRestoreWindowPos to restore the position the next time 
the user runs the program. 

The application name establishes a category in the profile—most 
programs use their company and program name as the application 
name string. The keyname labels a data item under that category—in 
this case, a window’s size and position. If your program has many win- 
dows it wishes to save, choose a different keyname for each window. 

This function also saves any presentation parameters attached to 
the window. 





WinSubclassWindow 





Sets the window’s window procedure address. 


SYNTAX 
PFNWP WinSubclassWindow(HWND hwnd, PFNWP p/nwp) 
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PARAMETERS 
hwnd - input 
The handle of the window to subclass. 


pfnwp - input 


The address of the subclass procedure. 


RETURNS 


The address of the original window procedure, or NULL if an error oc- 
curred. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinQueryWindowPtr -293, WinSetWindowPtr -314 


NOTES 


This function is effectively the same as WinSetWindowPtr with the 
QWP_PFNWP option except that this function also returns the original 
address. 

Subclassing lets you modify the behavior of an existing window by 
intercepting messages. After calling this function, PM will pass mes- 
sages intended for the window to your subclass procedure, which can 
modify the messages, add new messages, delete messages, or pass mes- 
sages unchanged to the original window procedure. 

You cannot use this function to subclass windows in other 
processes. 





@ WinWindowFromIiD 





Retrieves a child window’s handle, given its identifier. 


SYNTAX 
HWND WinWindowFromID(HWND hwndParent, ULONG 7d) 
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PARAMETERS 


hwndParent - input 

The handle of the child window’s parent. 
id - input 

The child window’s identifier. 


RETURNS 


The child window handle, or NULLHANDLE if an error occurred. 
Possible returns from WinGetLastError: 
0x1001 - PMERR INVALID HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinSetParent -306, WinQueryWindow -289, WinDlgBox -175, 
WinCreateStdWindow -433 


NOTES 


This function is especially useful for dialog boxes and standard win- 
dows. In a dialog box, the programmer typically defines the identifiers 
for dialog box controls, and can issue this function to determine the 
dialog box control window handles at runtime. In the standard win- 
dow, all of the window decorations, such as the title bar, have prede- 
fined identifiers, so a program can use this function to determine their 
window handles at runtime. For example, to determine the title bar’s 
handle from the client window procedure: 


hwndFrame = WinQueryWindow (hwnd, QW_PARENT ) ; 
hwndTitlebar = WinWindowFromID (hwndFrame, FID _TITLEBAR ); 





WinWindowFromPoint 





Retrieves a window handle, given a coordinate point. 


SYNTAX 


HWND WinWindowFromPoint(HWND hwndParent, PPOINTL ppil, 
BOOL /) 
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PARAMETERS 

hwndParent - input 

The handle of a parent window or HWND_DESKTOP. 

pptl - input 

Pass the address of a POINTL containing coordinates of a point, in pix- 
els. The coordinates should be relative to hwndParent’s lower left cor- 
ner. If you pass HWND_DESKTOP for hwndParent, the point should be 
relative to the screen’s lower left (screen coordinates). 


f- input 
Pass TRUE to test all descendants of hwndParent, FALSE to test only im- 
mediate children of hwndParent. 


RETURNS 


The window handle of the window under the point, or NULLHAN- 
DLE if there is no window or an error occurred. Note that this func- 
tion will return hwndParent if the point is over an area on the parent 
not covered by a child window. 

Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinMapWindowPoints -282, WinPtInRect -395 
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System 
nformation 





his chapter describes the functions provided by Presentation 

Manager that provide system information to programs, such as the 
current colors. Much of this system information is stored in the system 
profiles, OS2.INI and OS2SYS.INI, but these functions provide easy ac- 
cess to the system information so programs do not have to read the 
profiles directly. 


System Information Functions 





WinGetCurrentTime retrieves the current time (pg 326). 
WinGetSysBitmap retrieves handles for common system bitmaps 
(pg 327). 

WinQueryDesktopBkgnd retrieves information about the desktop win- 
dow’s background (pg 329). 
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WinQueryDesktopWindow retrieves the desktop window's handle 
(pg 331). 

WinQueryObjectWindow retrieves the object window’s handle (pg 332). 
WinQuerySysColor retrieves system color values (pg 333). 
WinQuerySysModalWindow retrieves the window handle of the cur- 
rent system modal window (pg 337). 

WinQuerySysPointer retrieves handles for common system pointers 
(pg 337). 

WinQuerySysPointerData retrieves information about common sys- 
tem pointers (pg 339). 

WinQuerySysValue retrieves common system setttings (pg 342). 
WinQueryVersion retrieves the operating system’s version number 
(pg 347). 

WinSetDesktopBkgnd changes the desktop window’s background 
(pg 348). 

WinSetSysColors changes system colors (pg 349). 
WinSetSysModalWindow makes a window system modal (pg 352). 
WinSetSysPointerData changes a system pointer (pg 353). 
WinSetSysValue changes a system value (pg 356). 





@ WinGetCurrentTime 





Retrieves the current time. 


SYNTAX 
ULONG WinGetCurrentTime (HAB hab) 


PARAMETERS 

hab - input 

Anchor block handle. 
RETURNS 


The number of milliseconds since the system was booted, or zero if an 
error occurred. 
Possible returns from WinGetLastError: 


X:0x104a - PMERR_ INVALID _HAB 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINTIMER 


SEE ALSO 
WinStartTimer -72 





WinGetSysBitmap 
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Retrieves handles for common system bitmaps. 


SYNTAX 


HBITMAP WinGetSysBitmap (HWND hwndDeskiop, ULONG 7d) 


PARAMETERS 
hwndDesktop - input 


The desktop window handle: HWND_DESKTOP or the handle returned 


by WinQueryDesktopWindow. 


id - input 


One of the following values: 


Identifier 
SBMP_BINCORNERS 
SBMP_CHECKBOXES 


SBMP_CHILDSYSMENU 
SBMP_CHILDSYSMENUDEP 
SBMP_COMBODOWN 
SBMP_DRIVE 

SBMP_ FILE 

SBMP_FOLDER 
SBMP_MAXBUTTON 
SBMP_MAXBUTTONDEP 
SBMP_MENUATTACHED 
SBMP_MENUCHECK 
SBMP_MINBUTTON 
SBMP_MINBUTTONDEP 


Description 
Button corners 


Contains 12 bitmaps showing check box 
and radio button bitmaps 


Child system menu 

Child system menu depressed 
Combo box down arrow 
Drive bitmap 

File bitmap 

Folder bitmap 

Maximize button 

Maximize button depressed 
Cascade menu 

Menu check mark 
Minimize button 


Minimize button depressed 
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SBMP_OLD_CHECKBOXES 


SBMP_OLD_CHILDSYSMENU 
SBMP_OLD_MAXBUTTON 
SBMP_OLD_MINBUTTON 
SBMP_OLD_RESTOREBUTTON 
SBMP_OLD_SBDNARROW 
SBMP_OLD_SBLFARROW 
SBMP_OLD_SBRGARROW 
SBMP_OLD_SBUPARROW 
SBMP_OLD_SYSMENU 
SBMP_PROGRAM 
SBMP_RESTOREBUTTON 
SBMP_RESTOREBUTTONDEP 
SBMP_SBDNARROW 
SBMP_SBDNARROWDEP 
SBMP_SBDNARROWDIS 
SBMP_SBLFARROW 
SBMP_SBLFARROWDEP 
SBMP_SBLFARROWDIS 
SBMP_SBRGARROW 
SBMP_SBRGARROWDEP 
SBMP_SBRGARROWDIS 
SBMP_SBUPARROW 
SBMP_SBUPARROWDEP 
SBMP_SBUPARROWDIS 
SBMP_SIZEBOX 
SBMP_SYSMENU 
SBMP_SYSMENUDEP 


1.x style check boxes and radio button 
bitmaps 


1.x style child system menu 

1.x style maximize button 

1.x style minimize button 

1.x style restore button 

1.x style scrolll bar down arrow 
1.x style scroll bar left arrow 
1.x style scroll bar right arrow 
1.x style scroll bar up arrow 

1.x style system menu 

Program bitmap 

Restore button 

Restore button depressed 
Scroll bar down arrow 

Scroll bar down arrow depressed 
Scroll bar down arrow disabled 
Scroll bar left arrow 

Scroll bar left arrow depressed 
Scroll bar left arrow disabled 
Scroll bar right arrow 

Scroll bar right arrow depressed 
Scroll bar right arrow disabled 
Scroll bar up arrow 

Scroll bar up arrow depressed 
Scroll bar up arrow disabled 
Size box bitmap 

System menu 


System menu depressed 
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SBMP_TREEMINUS Minus sign in a box 
SBMP_TREEPLUS Plus sign in a box 
RETURNS 


The bitmap handle, or NULLHANDLE if an error occurred. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 
0x1003 - PMERR_ PARAMETER OUT_OF_RANGE 
0x100a - PMERR_RESOURCE_NOT_FOUND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 
WinDrawBitmap -115, WinQuerySysPointer -337 


NOTES 


After retrieving the bitmap handle, you can determine its dimensions 
with GpiQueryBitmapInfoHeader, and you should call GpiDelete- 
Bitmap when you are finished with it. 

The SBMP_CHECKBOXES system bitmap contains three rows of 
four bitmaps that represent all of the check box and radio button 
states. 





WinQueryDesktopBkgnd 


Retrieves information about the desktop window’s background. 


SYNTAX 

BOOL WinQueryDesktopBkgnd (HWND hwndDesktop, PDESKTOP 
pdsk) 

PARAMETERS 


hwndDesktop - input 

The desktop window handle: HWND_DESKTOP or the handle returned 
by WinQueryDesktopWindow. 

pdsk- output 

Pass the address of a DESKTOP structure: 
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typedef struct _DESKTOP /® desk */ 
{ 

ULONG cbSize; 

HBITMAP hbm; 

LONG ry 

ULONG tL 

LONG 1TileCount ; 

CHAR SszFile[260]; 
DESKTOP; 


cbSize The structure’s length, in bytes. 
hbm The desktop’s bitmap handle or NULLHANDLE. 
x The x-coordinate of the desktop’s background image’s lower left 
corner, in pixels. 
y The y-coordinate of the desktop’s background image’s lower left 
corner, in pixels. 
fl A combination of the following flags: 
SDT_CENTER The bitmap is centered. 
SDT_NOBKGND There is no background bitmap. Instead, the 
desktop draws a color. 
SDT_PATTERN The background is a pattern. 
SDT_RETAIN The shell will remember the szFile name. 
SDT_SCALE ‘The bitmap is scaled to fit the desktop window. 
SDT_TILE The bitmap is repeated, rather than scaled to fill the 
desktop window. 
ITileCount The number of repeated bitmaps used to tile. 
szFile The path name of the bitmap file. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinSetDesktopBkgnd -348 
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NOTES 


This function can only be called by the shell—either the shell provided 
with the system or a replacement shell. 





WinQueryDesktopWindow 


Retrieves the desktop window's handle. 


SYNTAX 
HWND WinQueryDesktopWindow (HAB hab, HDC hdc) 


PARAMETERS 

hab - input 

Anchor block handle. 

hdc - input 

A window device context handle or NULLHANDLE. 


RETURNS 


The desktop window handle, or NULLHANDLE if an error occurred. 
Possible returns from WinGetLastError: 


Ox104a - PMERR_INVALID_ 0x207c - PMERR_INV_ 
HAB HDC 
OTHER INFO 


Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinQueryObjectWindow -332 


NOTES 


The desktop window is the parent of all visible windows and occupies 
the entire screen. This function returns its handle. In OS/2 Warp, the 
value of the handle is 0x80000001, but you shouldn’t depend on this 
value. Note that symbol HWND_DESKTOP defined in PMWIN.H is a 
synonym for this handle, but it has a different value: 0x00000001. Most 
functions accept either value as the desktop window handle. 
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@ WinQueryObjectWindow 


Retrieves the object window’s handle. 


SYNTAX 
HWND WinQueryObjectWindow (HWND hwndDesktop) 


PARAMETERS 


hwndDesktop - input 
The desktop window handle: HWND_DESKTOP or the handle returned 
by WinQueryDesktopWindow. 


RETURNS 


The object window’s handle, or NULLHANDLE if an error occurred. 
Possible returns from WinGetLastError: 


Ox1001 - PMERR_ INVALID _HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINSYS 


SEE ALSO 


WinQueryDesktopWindow -331, WinShowWindow -319, 
WinSetWindowPos -311, WinSetParent -306 


NOTES 


The object window is an invisible window with no parent. Any window 
that has the object window as an ancestor will also be invisible. Since 
the window manager doesn’t consult the object window hierarchy 
when passing paint messages, if you need to make a window invisible, 
the system will run faster if you make it an object window, rather than 
making it invisible with WinShowWindow. To use this technique, use 
WinSetParent to change the window's parent to the object window, 
and call WinSetParent again with the original parent to make the win- 
dow visible again. 

In OS/2 Warp, the object window’s handle is 0x80000002, but you 
shouldn’t depend on this value. Note that symbol HWND_OBJECT de- 
fined in PMWIN.H is a synonym for this handle, but it has a different 
value: 0x00000002. Most functions accept either value as the object 
window handle. 





@ WinQuerySysColor 


Retrieves system color values. 


SYNTAX 
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LONG WinQuerySysColor (HWND hwndDesktop, LONG index, 
LONG reserved) 


PARAMETERS 
hwndDesktop - input 


The desktop window handle: HWND_DESKTOP or the handle returned 


by WinQueryDesktopWindow. 
index - input 


The color to query. One of the following values: 


Index 
SYSCLR_ACTIVEBORDER 
SYSCLR_ACTIVETITLE 
SYSCLR_ACTIVETITLETEXT 


SYSCLR_ACTIVETITLETEXTBGND 


SYSCLR_APPWORKSPACE 
SYSCLR_BACKGROUND 
SYSCLR_BUTTONDARK 
SYSCLR_BUTTONDEFAULT 
SYSCLR_BUTTONLIGHT 
SYSCLR_BUTTONMIDDLE 
SYSCLR_DIALOGBACKGROUND 
SYSCLR_ENTRYFIELD 
SYSCLR_FIELDBACKGROUND 
SYSCLR_HELPBACKGROUND 
SYSCLR_HELPHILITE 
SYSCLR_HELPTEXT 
SYSCLR_HILITEBACKGROUND 


Description 

Active border 

Active title bar 

Text in active title bar 
Background of active title bar text 
Background of MDI windows 
Desktop background 

Dark pushbutton 3D color 
Default pushbutton border 

Light pushbutton 3D color 
Medium 3D pushbutton 

Dialog background 

Entryfield and listbox background 
Inactive control background 

Help background 

Help text highlight 

Help text 

Selection highlight background 
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SYSCLR_HILITEFOREGROUND Selection highlight foreground 


SYSCLR_ ICONTEXT Icon text in container 


SYSCLR_INACTIVEBORDER Inactive frame border 
SYSCLR_INACTIVETITLE Inactive title bar background 
SYSCLR_INACTIVETITLETEXT Inactive title bar text 


SYSCLR_INACTIVETITLETEXTBGND Inactive title bar text background 


SYSCLR_MENU 


SYSCLR_MENUDISABLEDTEXT 


SYSCLR_MENUHILITE 


SYSCLR_MENUHILITEBGND 


SYSCLR_MENUTEXT 
SYSCLR_OUTPUTTEXT 


SYSCLR_PAGEBACKGROUND 


SYSCLR_SCROLLBAR 
SYSCLR_SHADOW 


SYSCLR_SHADOWHILITEBGND 


SYSCLR_SHADOWHILITEFGND 


SYSCLR_SHADOWTEXT 


SYSCLR_TITLEBOTTOM 


SYSCLR_TITLETEXT 
SYSCLR_WINDOW 


SYSCLR_WINDOWFRAME 
SYSCLR_WINDOWSTATICTEXT 


SYSCLR_WINDOWTEXT 


reserved - input 
Set to zero. 


RETURNS 


The RGB value of the specified color. 


Menu background 

Disabled menu text 
Highlighted menu 
Highlighted menu background 
Normal menu text 

Window output text 

Window background 

Scroll bar background 

3D shadow background 


Text of shadow objects highlight 
background 


Text of shadow objects highlight 
foreground 


Text of shadow objects 
Bottom of title bar 
Title bar text 

Window background 
Window border 
Nonselectable text 


Selectable text 
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Possible returns from WinGetLastError: 


Ox1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINSYS 


SEE ALSO 


WinSetSysColors -349, WinQuerySysValue -342, 
WinInvalidateRect -138, WinQueryPresParam -285 


NOTES 


Windows can issue this function in response to the WM_SYSCOLOR- 
CHANGE message and then repaint themselves with the new colors. 
Since this function returns an RGB value, programs must set the pre- 
sentation space into RGB mode before using the RGB color. 

PM generates the WM_SYSCOLORCHANGE message when a pro- 
gram issues WinSetSysColors, or the user drags from the Scheme 
Palette while pressing the Alt key. 


EXAMPLE 


This code fragment from a window procedure uses presentation para- 
meters for its foreground and background colors. Since it uses a 
cached-micro presentation space, it also responds to font changes. If 
there are no presentation parameters attached to the window or its an- 
cestors up the owner tree, it queries the default system colors. 


case WM_SYSCOLORCHANGE: 
// repaint if system colors change (ALT drag from scheme palette) 
WinInvalidateRect ( hwnd, NULL, TRUE ); 
Feturn 0; 
case WM_PRESPARAMCHANGED: 
// repaint if presentation parameters change (drag from color or 
// font palettes) 
WinInvalidateRect ( hwnd, NULL, TRUE ); 
return 0; 
case WM_PAINT: 
{ 


BOOL fSuccess; // return from API 
LONG cb; // return from API 
RECT x2els // invalid rectangle 


HPS hps; // cached-micro PS handle 
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LONG 1ColorFore; // foreground color 
LONG 1ColorBack; // background color 
// query foreground color as presentation parameter 
// if none, use system-default foreground color 
cb = WinQueryPresParam ( hwnd 
, PP_FOREGROUNDCOLOR 
, o 
, NULL 
, sizeof ( LONG ) 
, &lColorFore 
, OFF 
if { @5 <= 0 | 
1ColorFore = WinQuerySysColor ( HWND_DESKTOP 
, SYSCLR OUTPUTTEXT, 0 }; 
// query background color as presentation parameter 
// i1£ none, use system-default background color 
cb = WinQueryPresParam ( hwnd 


, PP_BACKGROUNDCOLOR 


yO 

, NULL 

, Sizeof ( LONG ) 
, &lColorBack 

, OU }F 


1 { €b == ) 
1ColorBack = WinQuerySysColor ( HWND_DESKTOP 
, SYSCLR_WINDOW, O ); 

// retrieve a cached-micro PS 
hps = WinBeginPaint ( hwnd, NULLHANDLE, &rcl ); 

// set the PS into RGB mode and draw the background 
GpiCreateLogColorTable ( hps, 0, LCOLF_RGB, 0, 0, NULL ); 
WinFillRect ( hps, &rcl, l1ColorBack ); 

// set the foreground color 
GpiSetColor ( hps, 1ColorFore ); 


// draw text and graphics in foreground color 


WinEndPaint ( hps ); 
} 


return 0; 
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@ WinQuerySysModalWindow 


Retrieves the window handle of the current system modal window. 


SYNTAX 
HWND WinQuerySysModalWindow (HWND hwndDesktop) 


PARAMETERS 


hwndDeshtop - input 
The desktop window handle: HWND_DESKTOP or the handle returned 
by WinQueryDesktopWindow. 


RETURNS 
The system modal window’s handle, or NULLHANDLE if there is none. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinSetSysModalWindow -352, WinDlgBox -175, WinProcessDlg -190, 
WinMessageBox -184 


NOTES 


When a program issues WinSetSysModalWindow to assign the window 
as the current system modal window, PM routes all user input to that 
window, effectively disabling all other windows. This function returns 
the current system modal window's handle, if any. 





@ WinQuerySysPointer 


Retrieves handles for common system pointers. 


SYNTAX 


HPOINTER WinQuerysysPointer (HWND hwndDesktop, LONG id, 
BOOL ff) 
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PARAMETERS 
hwndDesktop - input 


The desktop window handle: HWND_DESKTOP or the handle returned 


by WinQueryDesktopWindow. 


id - input 


One of the following identifiers: 


identifier 
SPTR_APPICON 
SPTR_ARROW 
SPTR_DISPLAY PTRS 
SPTR_FILE 
SPTR_FOLDER 
SPTR_ICONERROR 
SPTR_ICONINFORMATION 
SPTR_ICONQUESTION 
SPTR_ICONWARNING 
SPTR_ILLEGAL 


SPTR_MOVE 
SPTR_MULTFILE 
SPTR_PROGRAM 
SPTR_SIZE 


SPTR_SIZENESW 


SPTR_SIZENS 
SPTR_SIZENWSE 


SPTR_SIZEWE 
SPTR_TEXT 
SPTR_WAIT 


Description 

Application icon 

Titled arrow (default system pointer) 
Program icon (same as SPTR_PROGRAM) 
File icon 

Folder icon 

Red slashed-circle icon 

White “i” in blue circle icon 

White “?” in green circle icon 

White “!” in green triangle icon 


Black circle with horizontal bar, plus tilted 
arrow 


Four-headed arrow icon 
Multiple file icon 
Program icon 


Not implemented (but defined in 
PMWIN.H) 


Tilted two-headed arrow, lower left to 
upper right 


Two-headed vertical arrow 


Tilted two-headed arrow, upper left to 
lower right 


Two-headed horizontal arrow 
Text I-beam icon (used by entry fields) 


Clock icon 
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f- input 
Pass TRUE to receive a copy of the system pointer, FALSE to receive a 
handle for the system pointer itself. If you pass TRUE, be sure to de- 


stroy the copy with WinDestroyPointer when you are finished with it. 


RETURNS 
Pointer handle if successful, NULLHANDLE if an error occurred. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_ INVALID HWND 
0x1003 - PMERR_PARAMETER_ OUT_OF_RANGE 
0x100a - PMERR_ RESOURCE _NOT_FOUND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 


WinQueryPointer -248, WinQuerySysPointerData -339, 
WinSetPointer -254, WinDrawPointer -121, WinDestroyPointer -237 


NOTES 

If you plan to hold the pointer across messages, you should specify 
TRUE for the fargument. Otherwise, other programs may have diffi- 
culty sharing the pointer. 





WinQuerySysPointerData 


Retrieves information about common system pointers. 


SYNTAX 

BOOL WinQuerySysPointerData (HWND hwndDesktop, ULONG 7d, 
PICONINFO picninf) 

PARAMETERS 


hwndDeshtop - input 

The desktop window handle: HWND_DESKTOP or the handle returned 
by WinQueryDesktopWindow. 

1dB - input 

One of the following identifiers: 
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Identifier 
SPTR_APPICON 
SPTR_ARROW 
SPTR_DISPLAY PTRS 
SPTR_FILE 
SPTR_FOLDER 
SPTR_ICONERROR 
SPTR_ICONINFORMATION 
SPTR_ICONQUESTION 
SPTR_ICONWARNING 
SPTR_ILLEGAL 


SPTR_MOVE 
SPTR_MULTFILE 
SPTR_PROGRAM 
SPTR_SIZE 


SPTR_SIZENESW 


SPTR_SIZENS 
SPTR_SIZENWSE 


SPTR_SIZEWE 
SPTR_TEXT 
SPTR_WAIT 


picninf - input/output 


Description 

Application icon 

Titled arrow (default system pointer) 
Program icon (same as SPTR_PROGRAM) 
File icon 

Folder icon 

Red slashed-circle icon 

White “1” in blue circle icon 

White “?” in green circle icon 

White “!” in green triangle icon 


Black circle with horizontal bar, plus tilted 
arrow 


Four-headed arrow icon 
Multiple file icon 
Program icon 


Not implemented (but defined in 
PMWIN.H) 


Tilted two-headed arrow, lower left to 
upper right 


Two-headed vertical arrow 


Tilted two-headed arrow, upper left to 
lower right 


Two-headed horizontal arrow 
Text I-beam icon (used by entry fields) 


Clock icon 


Pass the address of an IGONINFO structure that this function fills in. 
Before calling this function, set picninf->plconData to point to enough 
storage to hold the returned icon data and picninf->cbData to contain 
the icon data size. If you set picninf->cbIconData to zero, this function re- 
turns no icon data, but fills in that field with the byte count of storage 
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required. Thus, you can call this function twice, first to determine the 
storage size, and again after allocating the required storage. 


typedef struct _ICONINFO { /* icninf */ 
ULONG cb; 
ULONG fFormat; 
PSZ pszFileName; 
HMODULE hmod; 
ULONG resid; 
ULONG cbIconData; 
PVOID plIconData; 
} ICONINFO; 


cb The structure's length, in bytes. 

fFormat This function always assumes [CON_DATA, but other types 
are ICON_FILE, ICON_CLEAR, and ICON_RESOURCE. 

pszFileName Not used by this function, but contains a file name if 
format is I[CON_FILE. 

hmod_ Not used by this function, but contains a dynamic link library 
module handle, or NULLHANDLE if fFormatis IGON_RESOURCE. 

resid Not used by this function, but contains a resource identifier if 
format is IGON_RESOURCE. 

cbIconData The length, in bytes, of the icon data. If you set this to 
zero before issuing the function, it fills in this field with the required 
storage count. 

piconData Since this function assumes [CON_DATA, it uses this 
pointer to return a BITMAPFILEHEADER structure that describes 
the pointer. 


RETURNS 


TRUE if successful, FALSE otherwise. 

Possible returns from WinGetLastError: 

0x1001 - PMERR INVALID HWND 

0x1003 - PMERR PARAMETER OUT _OF RANGE 
0x100a - PMERR RESOURCE NOT FOUND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 


WinSetSysPointerData -353, WinQueryPointer -248, 
WinQuerySysPointer -337, WinSetPointer -254, WinDrawPointer -121, 
WinDestroyPointer -237 
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NOTES 


The returned BITMAPFILEINFOHEADER describes the pointer data, 
which consists of two bitmaps for monochrome pointers and three 
bitmaps for color pointers. 

This function is only available in OS/2 2.1 and later. 





@ WinQuerySysValue 


Retrieves common system setttings. 


SYNTAX 
LONG WinQuerySysValue (HWND hwndDeskiop, LONG index) 


PARAMETERS 


hwndDesktop - input 

The desktop window handle: HWND_DESKTOP or the handle returned 
by WinQueryDesktopWindow. 

index - input 

One of the identities listed in the following table. The Modify column 
indicates whether you can call WinSetSysValueto change the setting. 


Index Description Modify? 

SV_ALARM TRUE if WinAlarm sound enabled, FALSE Yes 
otherwise 

SV_ALTMNEMONIC Not documented f 

SV_ANIMATION TRUE if window open/close animated, Yes 
FALSE otherwise 

SV_ANIMATIONSPEED Not documented ? 

SV_BEGINDRAG Least significant 16 bits contain mouse Yes 


message ID to start a drag, most significant 
16 bits contain keybaord flag (KC_*) 


SV_BEGINDRAGKB Not documented ? 


SV_BEGINSELECT Least significant 16 bits contain mouse Yes 
message ID to start a selection, most 
significant 16 bits contain keyboard 
flag (KC_*) 


SV_BEGINSELECTKB Not documented ? 


SV_CHORDTIME 
SV_CICONTEXTLINES 
SV_CMOUSEBUTTONS 
SV_CONTEXTHELP 
SV_CONTEXTHELPKB 
SV_CONTEXTMENU 


SV_CONTEXTMENUKB 
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Not documented 
Not documented 
Count of mouse buttons 
Not documented 
Not documented 


Least significant 16 bits contain mouse 
message ID to request a pop-up menu, 


most significant 16 bits contain keyboard 


flag (KC_*) 


Least signficant 16 bits contain keystroke 


virtual key code (VK_*) to request a 
pop-up menu, most significant 16 bits 
contain keybaord flag (KC_*) 


SV_CPOINTERBUTTONS Not documented 


SV_CSYSVALUES 
SV_CTIMERS 
SV_CURSORLEVEL 
SV_CURSORRATE 
SV_CXALIGN 
SV_CXBORDER 
SV_CXBYTEALIGN 


SV_CXCHORD 
SV_CXDBLCLK 


SV_CXDLGFRAME 
SV_CXFULLSCREEN 


Not documented 

Count of available window timers 
Cursor hide level (see WinShowCursor) 
Cursor blink interval in milliseconds 
Not documented 

Thin window border width in pixels 


Horizontal increment of pixels for 
screen alignment 


Not documented 


Horizontal width in pixels of mouse 
double-click area 


Border width of dialog windows in pixels 


Width of client window in pixels of a 
maximized window 
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No 


Yes 


Yes 
No 


Yes 


Yes 
No 


SV_CXHSCROLLARROW Width of horizontal scroll bar arrow in pixels No 


SV_CXHSLIDER 


SV_CXICON 


Width of horizontal scroll bar thumb in 
pixels 


Standard icon width in pixels 


No 


No 
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SV_CXICONTEXTWIDTH Not documented No 
SV_CXMINMAXBUTTON Width of minimize and maximize buttons No 
in pixels 
The horizontal distance, in pixels, that Yes 


SV_CXMOTIONSTART 


SV_CXPOINTER 
SV_CXSCREEN 
SV_CXSIZEBORDER 
SV_CXVSCROLL 
SV_CYALIGN 
SV_CYBORDER 
SV_CYBYTEALIGN 


SV_CYCHORD 
SV_CYDBLCLK 


SV_CYDLGFRAME 
SV_CYFULLSCREEN 


SV_CYHSCROLL 
SV_CYICON 
SV_CYMENU 
SV_CYMINMAXBUTTON 


SV_CYMOTIONSTART 


SV_C 
SV_CYSCREEN 
SV_CYSIZEBORDER 


the user must move the mouse while 
pressing a button before the system gener- 
ates a WM_BUTTONxMOTIONSTR message 


Standard pointer width in pixels No 
Screen width in pixels No 
Sizing window border width in pixels Yes 
Vertical scroll bar width in pixels No 
Not documented : 

Thin border height in pixels Yes 
Vertical increment in pixels for screen No 
alignment 

Not documented ? 

Vertical increment in pixels of mouse Yes 


double-click area 
Border height of dialog windows in pixels _ Yes 


Height of client window in pixels of a No 
maximized window 


Horizontal scroll bar height in pixels No 
Standard icon height in pixels No 
Height in pixels of the standard action bar No 


Height of miminize and maximize buttons No 
in pixels 


The vertical distance, in pixels, that the Yes 
user must move the mouse while pressing a 
button before the system generates a 
WM_BUTTONxMOTIONSTR message 


Standard pointer height in pixels No 
Screen height, in pixels No 


Sizing window border height in pixels Yes 


SV_CYTITLEBAR 


SV_CYVSCROLLARROW 


SV_CYVSLIDER 


SV_DBLCLKTIME 


SV_DEBUG 


SV_ENDDRAG 


SV_ENDDRAGKB 
SV_ENDSELECT 


SV_ENDSELECTKB 


SV_ERRORDURATION 


SV_ERRORFREQ 


SV_EXTRAKEYBEEP 
SV_FIRSTSCROLLRATE 


SV_INSERTMODE 


SV_KBDALTERED 


SV_LOCKSTARTINPUT 


SV_MENUROLLDOWD- 
DELAY 


System Information 


Title bar height in pixels 
Height of vertical scroll bar arrow in pixels 
Height of vertical scroll bar thumb in pixels 


Interval in milliseconds between mouse 
clicks before the system generates a 
WM_BUTTONxDBLCLK message 


TRUE if debug system installed, FALSE 
otherwise 


Least significant 16 bits contain mouse 
message ID to end a drag, most significant 
16 bits contain keybaord flag (KC_*) 


Not documented 


Least significant 16 bits contain mouse 
message ID to end a selection, most signi- 
ficant 16 bits contain keyboard flag (KC_*) 


Not documented 


Duration of sound in milliseconds from 
WinAlarm with WA_ERROR 


Frequency of sound from WinAlarm with 
WA_ERROR 


Not documented 


The delay in milliseconds before a scroll 
bar starts automatic scrolling 


TRUE if the text entry is in insert mode, 
FALSE otherwise 


The hardware keyboard ID of any new 
keybaord attached to the system since boot 


Not documented 


The time in milliseconds that a menu 

waits before displaying a cascaded submenu 
when the user moves the highlight to the 
cascade menu item 


SV_MENUROLLUPDELAY The time in milliseconds that a menu waits 


before hiding a cascaded menu item when 
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Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 
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SV_MONOICONS 


SV_MOUSEPRESENT 
SV_NOTEDURATION 


SV_NOTEFREQ 


SV_NOTRESERVED 
SV_NUMBEREDLISTS 
SV_OPEN 


SV_OPENKB 
SV_POINTERLEVEL 


SV_PRINTSCREEN 
SV_RESERVEDFIRST 
SV_RESERVEDLAST 
SV_SCROLLRATE 


SV_SELECTKB 
SV_SETLIGHTS 


SV_SINGLESELECT 
SV_SWAPBUTTON 


SV_TASKLISTMOUSE 
ACCESS 


SV_TEXTEDIT 


the user moves the highlight away from the 
cascade menu item 


TRUE if the system attempts to load black 
and white icons or pointers instead of color 
from resource files 


TRUE if the system has a mouse attached 


Duration of sound in milliseconds from 
WinAlarm with WA_NOTE 


Frequency of sound from WinAlarm wth 
WA_NOTE 


Not documented 
Not documented 


Least significant 16 bits contain mouse 
message ID to generate a WM_OPEN 
message, most significant 16 bits contain 


keyboard flag (KC_*) 
Not documented 


The mouse pointer hide level (see 
WinShowPointer) 


TRUE if PrintScreen is enabled 
Not documented 
Not documented 


The delay in milliseconds between auto- 
matic scroll bar messages 


Not documented 


TRUE if WinSetKeyboardStateTable will 
change the keyboard lights (e.g. NumLock) 


Not documented 


True if left and right mouse buttons 
are reversed 


Not documented 


Least significant 16 bits contain mouse 
message ID to start editing text (e.g., icon 


Yes 


No 
Yes 


Yes 


Yes 


No 


Yes 


Yes 


Yes 


Yes 


Yes 
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text in a folder), most significant 16 bits 


contain keyboard flag (KC_*) 


SV_TEXTEDITKB Least significant 16 bits contain keystroke 
virtual key code (VK_*) to start editing text 
(e.g., icon text in a folder), most significant 


16 bits contain keyboard flag (KC_*) 


SV_TRACKRECTLEVEL The hide level of the tracking rectangel 
(see WinTractRect) 


SV_WARNINGDURATION Duration of sound in milliseconds from 
WinAlarm with WA_WARNING 


SV_WARNINGFREQOQ Frequency of sound from WinAlarm with 


WA_WARNING 


RETURNS 


The system value, or zero if an error occurred. 
Possible returns from WinGetLastError: 


0x1001 - PMERR INVALID HWND 
0x1003 - pmerr_parameter_out_of_RANGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINSYS 


SEE ALSO 
WinSetSysValue -356, WinQuerySysColor -333, WinAlarm -81 





WinQueryVersion 


Retrieves the operating system’s version number. 


SYNTAX 
ULONG WinQueryVersion (HAB hab) 


PARAMETERS 
hab - input 
Anchor block handle. 
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Yes 


No 


Yes 


Yes 
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RETURNS 


System version number. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


NOTES 


This function is obsolete—programs should call DosQuerySysInfo in- 
stead. 





@ WinSetDesktopBkgnd 


Changes the desktop window's background. 


SYNTAX 

HBITMAP WinSetDesktopBkgnd (HWND hwndDesktop, PDESKTOP 
pdsk) 

PARAMETERS 


hwndDeshtop - input 

The desktop window handle: HWND_DESKTOP or the handle returned 
by WinQueryDesktopWindow. 

pdsk-output 

Pass the address of a DESKTOP structure: 


typedef struct _DESKTOP /* ask */ 
{ 

ULONG cbSize; 

HBITMAP hbm; 


LONG x 

LONG Vi 

ULONG fi; 

LONG 1TileCount ; 

CHAR szFile[260]; 
} DESKTOP; 


cbSize The structure’s length, in bytes. 

hbm ‘The desktop’s bitmap handle, or NULLHANDLE. 

x The x-coordinate of the desktop’s background image’s lower left 
corner, in pixels. 
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y The y-coordinate of the desktop’s background image’s lower left 
corner, in pixels. 
fl A combination of the following flags: 
SDT_CENTER The bitmap is centered. 
SDT_NOBKGND There is no background bitmap. Instead the 
desktop draws a color. 
SDT_PATTERN The background is a pattern. 
SDT_RETAIN The shell will remember the szFile name. 
SDT_SCALE The bitmap is scaled to fit the desktop window. 
SDT_TILE The bitmap is repeated, rather than scaled to fill the 
desktop window. 
ITileCount The number of repeated bitmaps used to tile. 
szFile The path name of the bitmap file. 


RETURNS 


The handle of the bitmap used by the desktop, or NULLHANDLE if 
an error occurred. 
Possible returns from WinGetLastError: 


0Ox1001 - PMERR_ INVALID _HWND 


OTHER INFO: 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinQueryDesktopBkgnd -329 


NOTES 


This function can only be called by the shell, either the shell provided 
with the system or a replacement shell. 





WinSetSysColors 


Changes system colors. 


SYNTAX 


BOOL WinSetSysColors (HWND hwndDesktop, ULONG fl, ULONG 
ulFormat, LONG I[Start, ULONG count, 
PLONG alTable ) 
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PARAMETERS 


hwndDeshtop - input 

The desktop window handle: HWND_DESKTOP or the handle returned 

by WinQueryDesktopWindow. 

fl- input 

A combination of the following flags: 

LCOLF_ RESET The system should reset all of the system colors to 
their default values before setting the values as specified in this call. 

LCOLF_PURECOLOR The system should guarantee that all of the 
modified system colors are available on the current display so that 
the screen driver doesn’t need to simulate a color by dithering. 

ulFormat - input 

One of the following: 

LCOLF INDRGB The supplied table (alTable argument) is an array 
of 8-byte entries containing a system color index (see the (Start ar- 
gument) followed an RGB value. 

LCOLF_CONSECRGB The supplied table (alTable argument) is an 
array of 4-byte RGB values. 


Start - input 

Ignored unless you specify LCOLF_CONSECRGB in the ulFormat argu- 
ment, in which case it contains the starting color index to set. The fol- 
lowing table lists the indexes in ascending order. 


Index Description 


SYSCLR_SHADOWHILITEBGND 


SYSCLR_SHADOWHILITEFGND 


SYSCLR_SHADOWTEXT 
SYSCLR_ENTRYFIELD 
SYSCLR_MENUDISABLEDTEXT 
SYSCLR_MENUHILITE 
SYSCLR_MENUHILITEBGND 
SYSCLR_PAGEBACKGROUND 
SYSCLR_FIELDBACKGROUND 
SYSCLR_BUTTONLIGHT 


Text of shadow objects highlight 
background 


Text of shadow objects highlight 
foreground 


Text of shadow objects 

Entry field and listbox background 
Disabled menu text 

Highlighted menu 

Highlighted menu background 
Window background 

Inactive control background 


Light pushbutton 3D color 


SYSCLR_BUTTONMIDDLE 
SYSCLR_BUTTONDARK 
SYSCLR_BUTTONDEFAULT 
SYSCLR_TITLEBOTTOM 
SYSCLR_SHADOW 
SYSCLR_ICONTEXT 
SYSCLR_DIALOGBACKGROUND 
SYSCLR_HILITEFOREGROUND 
SYSCLR_HILITEBACKGROUND 


SYSCLR_INACTIVETITLETEXT 
BGND 


SYSCLR_ACTIVETITLETEXTBGND 
SYSCLR_INACTIVETITLETEXT 
SYSCLR_ACTIVETITLETEXT 
SYSCLR_OUTPUTTEXT 
SYSCLR_WINDOWSTATICTEXT 
SYSCLR_SCROLLBAR 
SYSCLR_BACKGROUND 
SYSCLR_ACTIVETITLE 
SYSCLR_INACTIVETITLE 
SYSCLR_MENU 
SYSCLR_WINDOW 
SYSCLR_WINDOWFRAME 
SYSCLR_MENUTEXT 
SYSCLR_WINDOWTEXT 
SYSCLR_TITLETEXT 
SYSCLR_ACTIVEBORDER 
SYSCLR_INACTIVEBORDER 
SYSCLR_APPWORKSPACE 
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Medium pushbutton 3D 

Dark pushbutton 3D color 
Default pushbutton border 
Bottom of title bar 

3D shadow background 

Icon text in container 

Dialog background 

Selection highlight foreground 
Selection highlight background 


Inactive title bar text background 


Background of active title bar text 
Inactive title bar text 

Text in active title bar 
Window output text 
Nonselectable text 

Scroll bar background 
Desktop background 

Active title bar background 
Inactive title bar background 
Menu background 

Window background 
Window border 

Normal menu text 
Selectable text 

Title bar text 

Active frame border 

Inactive frame border 


Background of MDI windows 
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SYSCLR_HELPBACKGROUND Help window background 
SYSCLR_HELPTEXT Help window text 
SYSCLR_HELPHILITE Help window highlighted text 


Count - input 

alTable - nput 

Pass an array of 8-byte (LCOLF_INDRGB) or 4-byte (LCOLF_CONSE- 
CRGB) entries as specified by the u/Format argument. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINSYS 


SEE ALSO 
WinQuerySysColor -333, WinSetSysValue -356 


NOTES 


PM generates the WM_SYSCOLORCHANGE message when a program 
issues this function or the user drags from the Scheme Palette while 
pressing the Alt key. 

Windows can issue WinQuerySysColor in response to the WM_SYS- 
COLORCHANGE message and then repaint themselves with the new 
colors. 





@ WinSetSysModalWindow 


Makes a window system modal. 


SYNTAX 
BOOL WinSetSysModalWindow (HWND hwndDesktop, HWND hwnd) 


PARAMETERS 


hwndDesktop - input 
The desktop window handle: HWND_DESKTOP or the handle re- 
turned by WinQueryDesktopWindow. 
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hwnd - input 
The handle of the window to make the current system modal window, 
or NULLHANDLE to cancel system modality. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinQuerySysModalWindow -337, WinMessageBox -184, 
WinDlgBox -175 


NOTES 


A window is considered modal if it disables another window or windows 
from receiving user input. Normally, modal windows are application 
modal—they only disable their owner window; for example, a modal di- 
alog box. However, a program may need to ensure that one of its win- 
dows is the only window in the system that can receive user input by 
making the system modal window. After issuing this function, PM en- 
sures that the user cannot interact with any other window in the system. 

To cancel the modality (but not necessarily destroy the window), 
call this function with NULLHANDLE for the hwnd argument. 

If there already is a system modal window, the window specified in 
this function replaces the current system modal window. 

You should only issue this function in response to a user-input 
message. 





WinSetSysPointerData 


Changes a system pointer. 


SYNTAX 


BOOL WinSetSysPointerData (HWND hwndDesktop, ULONG id, 
PICONINFO picninf) 
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PARAMETERS 
hwndDesktop - input 


The desktop window handle: HWND_DESKTOP or the handle returned 
by WinQueryDesktopWindow. 


id-input 


One of the following identifiers: 


identifier 
SPTR_APPICON 
SPTR_ARROW 
SPTR_DISPLAY PTRS 
SPTR_FILE 
SPTR_FOLDER 
SPTR_ICONERROR 
SPTR_ICONINFORMATION 
SPTR_ICONQUESTION 
SPTR_ICONWARNING 
SPTR_ILLEGAL 


SPTR_MOVE 
SPTR_MULTFILE 
SPTR_PROGRAM 
SPTR_SIZE 
SPTR_SIZENESW 


SPTR_SIZENS 
SPTR_SIZENWSE 


SPTR_SIZEWE 
SPTR_TEXT 
SPTR_WAIT 


picninf - input 


Description 

Application icon 

Titled arrow (default system pointer) 
Program icon (same as SPTR_PROGRAM) 
File icon 

Folder icon 

Red slashed-circle icon 

White “1” in blue circle icon 

White “?” in green circle icon 

White “!” in green triangle icon 


Black circle with horizontal bar, plus tilted 
arrow 


Four-headed arrow icon 

Multiple file icon 

Program icon 

Not implemented (but defined in PMWIN.H) 


Tilted two-headed arrow, lower left to upper 
right 


Two-headed vertical arrow 


Tilted two-headed arrow, upper left to 
lower right 


Two-headed horizontal arrow 
Text I-beam icon (used by entry fields) 


Clock icon 


Pass the address of an JCONINFO structure: 
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<typedef struct _ICONINFO { /* icninf */ 


ULONG es 
ULONG fFormat; 
PSZ pszFileName; 
HMODULE hmod; 
ULONG resid; 
ULONG cbIconData; 
PVOID piconData; 
} ICONINFO; 


cb The structure’s length, in bytes. 
fFormat One of the following: 
ICON_DATA The plconData field points to a BITMAPFILE- 
HEADER or BITMAPFILEHEADERZ that describes the pointer. 
ICON_FILE The pszkileName field references a file containing a 
pointer definintion. 
IGON_CLEAR The system should reset the pointer to its default. 
IGON_RESOURCE The mod and resid fields reference a pointer 
resource. 
pszFileName Points to a file name string if Format is ICON_FILE. 
hmod Contains a dynamic link library module handle or NULL- 
HANDLE if fFormatis IGON_RESOURCE. 
resid Contains a resource identifier if Format is IGCON_RESOURCE. 
cbIconData The length, in bytes, of the icon data. Ignored unless 
fFormatis IGON_DATA. 
piconData Points to a BITMAPFILEHEADER or BITMAPFILEHEAD- 
ER2 that describes the pointer if Format is ICON_DATA. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR_INVALID_HWND 
0x1003 - PMERR_ PARAMETER OUT_OF_RANGE 
0x100a - PMERR_ RESOURCE_NOT_FOUND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINPOINTERS 


SEE ALSO 


WinQueryPointer -248, WinQuerySysPointerData -339, 
WinSetPointer -254, WinDrawPointer -121, WinDestroyPointer -237 
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NOTES 


This function is only available in OS/2 2.1 and later. 
The system remembers the pointer change across boots. 





@ WinSetSysValue 


Changes a system value. 


SYNTAX 


BOOL WinSetSysValue (HWND hwndDesktop, LONG id, 
LONG value) 


PARAMETERS 


hwndDesktop - input 

The desktop window handle: HWND_DESKTOP or the handle returned 
by WinQueryDesktopWindow. 

id - input 

System value identifier. See WinQuerySysValue for a listing of identifiers. 
value - input 

System value to set. See WinQuerySysValue for a listing of identifiers 
and corresponding values. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1001 - PMERR INVALID HWND 
0x1003 - pmerr_parameter_out_of_RANGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINSYS 


SEE ALSO 


WinQuerySysValue -342, WinSetSysColors -349, 
WinQuerySysColor -333, WinBroadcastMsg -35 


NOTES 


After changing one of the system values, you should notify all top-level 
frame windows by broadcasting the WM_SYSVALUECHANGED message. 








n atom is an integer representation of a text string. Presentation 

Manager uses atoms internally for clipboard formats and window 
class names, and programs can use atoms to save storage and to speed 
string comparisons. In other words, if your program compares the 
same strings over and over, you can use atoms for better perfomance, 
since an integer comparison is faster than a string comparison. 

An atom table is a set of text strings and their corresponding atom 
values, much like a hash table. There is a system-wide global atom table 
available to all programs, and programs can create their own local 
atom tables. 

A program can use WinAddAtom (pg 359) to add an atom string 
to an atom table and receive the atom value. If the same text string is 
added more than once to an atom table, the atom table increments the 
atom’s use count, but doesn’t insert a new entry. 

Atom tables also support a special kind of atom, called an integer 
atom. Integer atoms must have values less than Oxc000 (49152 deci- 
mal). Atoms returned by WinAddAtom will have values greater than 
Oxc000. Integer atoms are not stored in the atom table. There are 
three ways to specify an integer atom: 
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A string with the form #XXXXX, where XXXXX is a number, the atom 
value. For example, #12345 is the string for the integer atom of 
value 12345. 

A ULONG containing Oxffffxxxx, where xxxx is the atom value. For ex- 
ample, Oxffff3039 specifies an integer atom of value 12345 (0x3039 
is 12345 decimal). You must cast the ULONG to a PSZ in functions 
that require an atom string. 

A five-character string with the first character ! and the remaining four 
characters containing the integer atom value. For example, this 
string also specifies the integer atom 12345: 


CHAR ez[5] = { ‘1*, 0x39, Ox30, 0, 0 }; 
Note that the bytes are reversed as normal for Intel CPUs. 
PM internally uses integer atoms, for example, the preregistered win- 


dow class WC_FRAME is defined as ((PSZ) Oxffff0001L) in PMWIN.H, 
which specifies the integer atom of value 1. 


Atom Functions 





WinAddAtom returns the atom value for a string (pg 359). 
WinCreateAtomTable creates a local atom table (pg 360). 
WinDeleteAtom removes a string from an atom table (pg 361). 
WinDestroyAtomTable deletes a local atom table (pg 362). 
WinFindAtom returns an atom from an atom table, given a text string 
(pg 362). 

WinQueryAtomLength returns the character count of an atom text 
string (pg 363). 

WinQueryAtomName returns a text string from an atom table, given 
an atom (pg 365). 

WinQueryAtomUsage returns an atom’s use count (pg 366). 
WinQuerySystemAtomTable returns the system atom table’s handle 


(pg 367). 


Atoms 359 





@® WinAddAtom 





Returns the atom value for a string. 


SYNTAX 
ATOM WinAddAtom (HATOMTBL hatomibl, PSZ psz) 


PARAMETERS 


hatomtbl-input 

The handle of the local or system atom table. You can create a local 
atom table with WinCreateAtom Table, and retrieve the handle of the 
system atom table with WinQuerySystemAtom Table. 

pszinput 

The atom string or integer atom specifier. See the beginning of this 
chapter for a discussion of integer atoms. 


RETURNS 


The atom value, or 0 if an error occurs. If the psz input refers to an in- 
teger atom, this function returns the integer atom value. The ATOM 


data type is a 32-bit value. 

Possible returns from WinGetLastError: 

0x1013-PMERR INVALID _ 0x1014-PMERR INVALID _ 
HATOMTBL ATOM 


0x1015 - PMERR_INVALID_ATOM_NAME 
0Ox1016 - PMERR_ INVALID_INTEGER_ATOM 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINATOM 


SEE ALSO 


WinCreateAtomTable -360, WinDeleteAtom -361, 
WinDestroyAtomTable -362, WinFindAtom -362, 
WinQueryAtomLength -363, WinQueryAtomName -365, 
WinQueryAtom Usage -366, WinQuerySystemAtomTable-367 


NOTES 


If you call this function with the same string more than once, this func- 
tion doesn’t add a new entry to the table; instead, it increments the ex- 
isting entry’s usage count. You can decrement the usage count with 
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WinDeleteAtom, and query the usage count with WinQueryAtom- 
Usage. 





@ WinCreateAtomTable 


Creates a local atom table. 


SYNTAX 
HATOMTBL WinCreateAtomTable (ULONG cb, ULONG wlBuckets) 


PARAMETERS 

cb-input 

The initial size of the atom table, in bytes. WinAddAtom will expand 
the table as needed. You can pass zero here to use the default size, 
which is large enough to contain the overhead of the atom table (the 
hash table) with no entries. 

ulBuckets-input 

The size of the internal hash table. Pass zero to use the default size of 
37 or pass a prime number for best performance. 


RETURNS 
The atom table handle, or NULLHANDLE if an error occurred. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINATOM 


SEE ALSO 


WinAddAtom -359, WinDeleteAtom -361, WinDestroyAtomTable -362, 
WinFindAtom -362, WinQueryAtomLength -363, 
WinQueryAtomName -365, WinQueryAtom Usage -366, 
WinQuerySystemAtomTable -367 


NOTES 


This function creates an atom table that is private to the calling 
process. OS/2 destroys the atom table if the process exits without call- 
ing WinDestroyAtomTable. 

You can retrieve a handle to the global system atom table with 
WinQuerySystemAtom Table. 
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@ WinDeleteAtom 





Removes a string from an atom table. 


SYNTAX 
ATOM WinDeleteAtom (HATOMTBL hatomtbl, ATOM atom) 


PARAMETERS 


hatomtbl-input 

The handle of the local or system atom table. You can create a local 
atom table with WinCreateAtom Table, and retrieve the handle of the 
system atom table with WinQuerySystemAtom Table. 

atom-input 

The atom to remove. 


RETURNS 


Zero if successful, the input atom otherwise. 
Possible returns from WinGetLastError: 


0x1013 - PMERR_INVALID_ 0Ox1014 - PMERR_INVALID_ 
HATOMTBL ATOM 
OTHER INFO 


Include file: pmwin.h Define: INCL_WINATOM 


SEE ALSO 


WinAddAtom -359, WinCreateAtomTable -360, 
WinDestroyAtomTable -362, WinFindAtom -362, 
WinQueryAtomLength -363, WinQueryAtomName -365, 
WinQueryAtom Usage -366, WinQuerySystemAtomTable-367 


NOTES 


This function actually decrements the indicated atom’s usage count 
and only removes it if the usage count is zero. 

If the input atom refers to an integer atom, this function takes no 
other action than to return zero. 


362 OS/2 WARP Presentation Manager API 





@ WinDestroyAtomTable 


Deletes a local atom table. 


SYNTAX 
HATOMTBL WinDestroyAtomTable (HATOMTBL hatomtbl) 


PARAMETERS 


hatomtbl-input 
The handle of a local atom table created by WinCreateAtomTable. 


RETURNS 


Zero if successful, the input atom table handle otherwise. 
Possible returns from WinGetLastError: 


(0x1013 - PMERR_ INVALID HATOMTBL 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINATOM 


SEE ALSO 


WinAddAtom -359, WinCreateAtom Table -360, WinDeleteAtom -361, 
WinFindAtom -362, WinQueryAtomLength -363, 
WinQueryAtomName -365, WinQueryAtom Usage -366, 
WinQuerySystemAtomTable-367 


NOTES 


You cannot use this function to delete the system atom table. 





@ WinFindAtom 





Returns an atom from an atom table, given a text string. 


SYNTAX 
ATOM WinFindAtom (HATOMTBL hatomtbl, PSZ psz) 
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PARAMETERS 


hatomibl-input 

The handle of the local or system atom table. You can create a local 
atom table with WinCreateAtom Table, and retrieve the handle of the 
system atom table with WinQuerySystemAtom Table. 

psz-input 

The atom string or integer atom specifier. See the beginning of this 
chapter for a discussion of integer atoms. 


RETURNS 


The atom value, or zero if an error occurs. If the psz input refers to an 
integer atom, this function returns the integer atom value. The ATOM 


data type is a 32-bit value. 

Possible returns from WinGetLastError: 

0x1013 - PMERR INVALID _ 0x1014-PMERR INVALID _ 
HATOMTBL ATOM 


0x1015 - PMERR_INVALID_ATOM_NAME 
0x1016 - PMERR_INVALID_INTEGER_ ATOM 
0x1017 - PMERR_ATOM_NAME_NOT_FOUND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINATOM 


SEE ALSO 


WinAddAtom -359, WinCreateAtom Table -360, WinDeleteAtom -361, 
Win DestroyAtomTable -362, WinQueryAtomLength -363, 
WinQueryAtomName -365, WinQueryAtom Usage -366, 
WinQuerySystemAtomTable -367 


NOTES 


This function differs from WinAddAtom in that it doesn’t add new 
strings to the atom table and doesn’t increment the usage count of ex- 
isting atoms. 





WinQueryAtomLength 


Returns the character count of an atom text string. 
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SYNTAX 
ULONG WinQueryAtomLength (HATOMTBL hatomibl, ATOM atom) 


PARAMETERS 


hatomtbl-input 

The handle of the local or system atom table. You can create a local 
atom table with WinCreateAtom Table, and retrieve the handle of the 
system atom table with WinQuerySystemAtomTable. 

atom-input 

The atom to query. 


RETURNS 


The number of characters in the atom string, or zero if an error oc- 
curred. The returned count doesn’t include the null terminator. If the 
atom is an integer atom, this function returns six. 

Possible returns from WinGetLastError: 


0Ox1013 - PMERR_INVALID_ 0Ox1014 - PMERR_INVALID_ 
HATOMTBL ATOM 

0x1015 - PMERR_INVALID_ATOM_NAME 

0Ox1016 - PMERR_INVALID_ INTEGER ATOM 

0x1017 - PMERR_ATOM_NAME_NOT_FOUND 


OTHER INFO 
Include file: pmwin.h Define: INCGL_WINATOM 


SEE ALSO 


WinAddAtom -359, WinCreateAtom Table -360, WinDeleteAtom -361, 
WinDestroyAtomTable -362, WinFindAtom -362, 
WinQueryAtomName -365, WinQueryAtom Usage -366, 
WinQuerySystemAtomTable -367 


NOTES 


A program can use this function to determine the amount of storage 
to allocate before calling WinQueryAtomName. This function always 
returns integer atoms in the form #XXXXX where XXXXX is the in- 
teger atom value. 
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@ WinQueryAtomName 


Returns a text string from an atom table, given an atom. 


SYNTAX 


ULONG WinQueryAtomName (HATOMTBL hatomtbl, ATOM atom, 
PSZ psz, ULONGcd) 


PARAMETERS 


hatomtbl - input 

The handle of the local or system atom table. You can create a local 
atom table with WinCreateAtom Table, and retrieve the handle of the 
system atom table with WinQuerySystemAtom Table. 

atom - input 

The atom to query. 

psz - output 

Pass the the address of a character string that this function will initial- 
ize with the atom string. 

cb - input 

The number of bytes in the output string. 


RETURNS 


The number of bytes copied to the output string, or zero if an error oc- 
curred. 
Possible returns from WinGetLastError: 


Ox1013 - PMERR_INVALID_ Oxl014- PMERR_ INVALID _ 
HATOMTBL ATOM 

Ox1015 - PMERR_INVALID_ATOM_NAME 

0Ox1016 - PMERR_ INVALID_INTEGER_ATOM 

0x1017 - PMERR_ATOM_NAME_ NOT_FOUND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINATOM 


SEE ALSO 


WinAddAtom -359, WinCreateAtomTable -360, WinDeleteAtom -361, 
WinDestroyAtomTable -362, WinFindAtom -362, 
WinQueryAtomLength -363, WinQueryAtomUsage -366, 
WinQuerySystemAtomTable-367 
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NOTES 


You can call WinQueryAtomLength to determine the number of bytes 
required for the output string. 





@ WinQueryAtomUsage 


Returns an atom’s use count. 


SYNTAX 
ULONG WinQueryAtomUsage (HATOMTBL hatomtbl, ATOM atom) 


PARAMETERS 


hatomtbl - input 

The handle of the local or system atom table. You can create a local 
atom table with WinCreateAtom Table, and retrieve the handle of the 
system atom table with WinQuerySystemAtomTable. 

atom - input 

The atom to query. 


RETURNS 


65536 if the input atom is an integer atom, or the usage count for 
string atoms, or zero if an error occurred. 
Possible returns from WinGetLastError: 


0x1013 - PMERR_INVALID_ 0x1014 - PMERR_ INVALID _ 
HATOMTBL ATOM 

0x1015 - PMERR_INVALID_ATOM_NAME 

0x1016 - PMERR_INVALID_INTEGER_ATOM 

0x1017 - PMERR_ATOM_NAME_NOT_FOUND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINATOM 


SEE ALSO 


WinAddAtom -359, WinCreateAtom Table -360, WinDeleteAtom -361, 
WinDestroyAtom Table -362, WinFindAtom -362, 
WinQueryAtomLength -363, WinQueryAtomName -365, 
WinQuerySystemAtomTable-367 
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@ WinQuerySystemAtomTable 


Returns the system atom table’s handle. 


SYNTAX 
HATOMTBL WinQuerySystemAtomTable ( ) 


PARAMETERS 


None 


RETURNS 


The system atom table’s handle. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINATOM 


SEE ALSO 

WinAddAtom -359, WinCreateAtom Table -360, WinDeleteAtom -361, 
WinDestroyAtomTable -362, WinFindAtom -362, 
WinQueryAtomLength -363, WinQueryAtomName -365, 
WinQueryAtom Usage -366 


NOTES 


The system atom table is global to all processes and cannot be destroyed. 
Processes can create private atom tables with WinCreateAtomTable. 
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sing the clipboard, users can transfer data between programs or 

within the same program. Most programs provide Cut, Copy, and 
Paste menu items so the user can read and write data via the clipboard. 
The clipboard consists of a small amount of shared memory owned by 
Presentation Manager and the functions described in this chapter. It’s 
important to note that the clipboard doesn’t actually store the shared 
data; instead, programs write pointers to the data onto the clipboard. 

When the user chooses Cut or Copy, the program can write more 
than one pointer to the selected data to the clipboard—the pointers 
reference the same data in different formats. For example, a word pro- 
cessing program could store the ASCII text for a selected paragraph, as 
well as a bitmap image of the selected paragraph. Then the receiving 
program can choose the format it prefers. 
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Dynamic Data Exchange (DDE) is conceptually similar to the clip- 
board in that it lets programs transfer data. Unlike the clipboard, DDE 
lets programs establish hot links, so that if the user changes data in one 
program, it is automatically updated in another. DDE is essentially a 
message protocol that programs follow to begin a conversation, estab- 
lish a link, transfer data, and terminate the conversation. 

In a typical DDE conversation, one party, called the DDE server, 
passes data to the DDE client. The client must start the conversation and 
then request the link with the server. ‘The server receives the initiate re- 
quest, the link request, and then asynchronously posts data to the DDE 
client whenever the data changes. Either party can terminate the con- 
versation. 

Since DDE is also supported by Microsoft Windows, it’s possible 
for PM and Windows programs to communicate via DDE when both 
are running on an OS/2 system. 


Clipboard Formats 





Presentation Manager defines several standard clipboard formats, de- 
scribed below. In addition, a program can register a private clipboard 
format using WinAddAtom (pg 359) on the system atom table. Each 
format is represented by a unique constant (CF_ value) defined in 
PMWIN.H or by the atom returned by WinAddAtom. 


CF_BITMAP Store a handle to a standard PM bitmap. 

CF_DSPBITMAP Store a handle to a standard PM bitmap. This for- 
mat is for programs that register a private format so they can provide 
a bitmap representation of the private format for a clipboard viewer. 

CF DSPMETAFILE Store a handle to a PM metafile. This format is 
for programs that register a private format so they can provide a 
metafile representation of the private format for a clipboard viewer. 

CF_DSPTEXT Store a pointer to givable shared memory (allocated 
with DosAllocSharedMem). This format is for programs that regis- 
ter a private format so they can provide a text representation of the 
private format for a clipboard viewer. See CF_TEXT. 

CF METAFILE Store a handle to a PM metafile. 

CF_PALETTE Store a handle to a palette. 
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CF_TEXT Store a pointer to givable shared memory (allocated with 
DosAllocSharedMem). This format allows only printable charac- 
ters—no formatting characters are accepted except for carriage re- 
turn, line feed, tab and the required null-terminating character. 


Clipboard and DDE Functions 





WinCloseClipbrd releases access to the clipboard (pg 370). 
WinDdelnitiate starts a DDE conversation (pg 371). 

WinDdePostMsg passes a message between DDE conversation partners 
(pg 373). 

WinDdeRespond lets a potential DDE server respond to a conversa- 
tion initiation request (pg 375). 

WinEmptyClipbrd deletes everything from the clipboard and frees 
data (pg 377). 

WinEnumClipbrdFmts enumerates the formats on the clipboard 
(pg 378). 

WinOpenClipbrd gains access to the clipboard (pg 378). 
WinQueryClipbrdData retrieves a pointer or handle from the clip- 
board (pg 379). 

WinQueryClipbrdFmtInfo determines if a format is available (pg 381). 
WinQueryClipbrdOwner retrieves the window handle of the clipboard 
owner (pg 382). 

WinQueryClipbrdViewer retrieves the window handle of the clipboard 
viewer (pg 382). 

WinSetClipbrdData writes a pointer or a handle to the clipboard (pg 
BOO}. 

WinSetClipbrdOwner assigns the clipboard owner (pg 385). 
WinSetClipbrdViewer assigns the clipboard viewer (pg 386). 





WinCloseClipbrd 


Releases access to the clipboard. 


SYNTAX 
BOOL WinCloseClipbrd (HAB had) 
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PARAMETERS 
hab - input 
Anchor block handle. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCLIPBOARD 


SEE ALSO 
WinOpenClipbrd -378, WinSetClipbrdViewer -382 


NOTES 


A program that opens the clipboard must issue this function when it is 
finished reading or writing the clipboard—only one program can have 
the clipboard open at a time. 

After calling this function, the program can no longer access the 
pointers or handles stored on or retrieved from the clipboard. If the 
program retrieves pointers or handles, it must copy the data they refer 
to before closing the clipboard. For example, if the program retrieves 
a metafile handle, it can issue GpiCopyMetaFile to create a local copy 
of the metafile before closing the clipboard. 

If you write the clipboard, then this function sends WM_DRAW- 
CLIPBOARD to any registered clipboard viewer. 





WinDdelnitiate 





Starts a DDE conversation. 


SYNTAX 


BOOL WinDdelnitiate (HWND hwndDDEChent, PSZ pszApp, PSZ 
pszTopic, POONVCONTEXT pContext ) 


PARAMETERS 


hwndDDEChent - input 
The handle of the DDE client that’s initiating the DDE converstation. 
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pszApp - input 

The DDE application name string. This is typically the file name of the 
DDE server executable. 

pszTopic - input 

The DDE topic name string. This is typically a data file name that the 
server has open or will open. 

pContext - input 

Pass the address of a CONVCONTEXT structure: 


typedef struct _CONVCONTEXT /* cctxt */ 
{ 

ULONG cb; 

ULONG fsContext ; 

ULONG idCountry; 

ULONG usCodepage; 

ULONG usLangID; 

ULONG usSubLangID; 
} CONVCONTEXT; 


fsContext Either DDECTXT_CASESENSITIVE or zero. 

idCountry Country code. 

usCodePage Code page value. 

usLangID Language identifier, or zero to indicate no language in- 
formation. 

usSubLangID Language identifier, or zero to indicate no language 
information. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file :pmwin.h Define: INCL_WINDDE 


SEE ALSO 
WinDdeRespond -375, WinDdePostMsg -373 


NOTES 


A DDE client program issues this function to request a conversation 
with a particular server, by passing the server’s name string (typically, 
the server’s EXE file name) in pszServerName. The server will receive 
the WM_DDE_INITIATE message, where it examines the server name 
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and topic name, and issues WinDdeRespond if the strings are correct. 
If the server responds, the DDE client will receive the WM_DDE_INI- 
TIATE_ACK message. 

Alternatively, the DDE client can assemble a list of potential servers 
by passing a zero-length string for the server name (not a NULL 
pointer) and SZDDESYS_TOPIC (defined as “System” in PMWIN.H) as 
the topic string. All potential servers should respond, passing their 
server name. 

If the client passes a zero-length string for the topic string, a server 
should respond once for each of the topics it supports. This lets the 
DDE client assemble a list of topics. 





WinDdePostMsg 


Passes a message between DDE converstation partners. 


SYNTAX 


BOOL WinDdePostMsg (HWND hwndSrc, HWND hwndDst, ULONG 
idMsg, PDDESTRUCT pdde, ULONG options) 


PARAMETERS 

hwndSrc - input 

The handle of the source of the message, either the DDE client or 
DDE server. 

hwndDst - input 

The handle of the destination window, either the DDE client or DDE 
server. 

idMsg - input 

One of the following: 


WM_DDE_ ACK Acknowledge or reject (NAK) a DDE message. 

WM_DDE_ ADVISE DDE client posts this to request a link and passes 
topic string and data format. Server ACKs or NAKs. 

WM_DDE_DATA DDE server posts this to pass data to the DDE 
client. After a link is established, server posts this asynchronously. 
DDE client ACKs or NAKs. 

WM_DDE_EXECUTE DDE client posts this to pass commands (such 
as macros) to the server. Server ACKs or NAKs. 

WM_DDE_POKE Either party posts this to pass a nonlinked data 
item. Recipient ACKs or NAKs. 
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WM_DDE_REQUEST DDE client posts this to request a nonlinked 
data item from the server. Server posts WM_DDE_DATA or NAKs. 

WM_DDE_TERMINATE Either party posts this to terminate the 
conversation. 

WM_DDE_UNADVISE DDE client posts this to break a link. Server 
ACKs or NAKs. 


pdde - input 

Pass the address of a DDE structure. This structure must be allocated 
with DosAllocSharedMem with the OBJ GIVEABLE flag. The poster 
must also call DosGiveSharedMem to assign memory addressability for 
the recipient. 


typedef struct _DDESTRUCT /* dde */ 
{ 

ULONG cbData; 

USHORT fsStatus; 

USHORT usFormat; 

USHORT offszItemName; 

USHORT offabData; 
} DDESTRUCT: 


cbData_ The size of the structure, in bytes. 

fsStatus Any combination of the following flags: 
DDE_FACK Positive acknowledgment. Used in WM_DDE_ACK. 
DDE_FACKREQ Poster requires an acknowledgment. 
DDE_FAPPSTATUS Available for application use. 
DDE_FBUSY Recipient is busy. 
DDE_FNODATA Used in WM_DDE_ADVISE to request no data. 
DDE_FRESERVED Reserved. 
DDE_FRESPONSE Response to WM_DDE_REQUEST. 
DDE_NOTPROCESSED Unrecognized DDE message. 

usFormat The format of the data. Same as the clipboard data for- 
mats. See the beginning of this chapter for a description of these 
formats. 

offszItemName Contains the offset from the structure start to the 
item string. 

offabData Contains the offset from the structure start to the data to 
be passed. 


Options - input 
One of the following values: 
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DDEPM_RETRY Ifyou set this flag and the destination queue is full, 
this function retries the post every second until it is successful. 

DDEPM_NOFREE Without this flag, this function frees the DDE 
structure’s memory on behalf of the caller, removing the caller’s ad- 
dressability. With this flag, the caller can reuse the structure, but 
must free the memory when finished. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDDE 


SEE ALSO 


WinDdelnitiate -371, WinDdePostMsg -373, 
WinQueryWindowProcess -292 


NOTES 


After a conversation is established with WinDdelInitiate and WinDde- 
Respond, the conversation parties communicate with this function. 
Since the two parties can be in separate processes, the memory passed 
between them must be shared. It is the poster’s responsibility to allo- 
cate the DDE structure in shared memory and make it addressable by 
the recipient. The poster can call WinQueryWindowProcess to retreive 
the recipient’s process identifier so it can assign addressability with 
DosGiveSharedMem. The recipient must free the storage with Dos- 
FreeMem. 





WinDdeRespond 


Lets a potential DDE server respond to a conversation initiation re- 
quest. 


SYNTAX 


MRESULT WinDdeRespond (HWND hwndDDEClent, HWND 
hwndDDEServer, PSZ pszApp, PSZ 
pszTopic, PCONVCONTEXT pContext) 


376 OS/2 WARP Presentation Manager API 


PARAMETERS 


hwndDDEChent - input 

The handle of the DDE client that’s initiating the DDE converstation. 
hwndDDEServer - input 

The handle of the DDE server responding to the initiate request. 
pszApp - input 

The DDE application name string. This is typically the file name of the 
DDE server executable. 

pszTopic - input 

The DDE topic name string. This is typically a data file name that the 
server has open or will open. 

Context - input 

Pass the address of a CONVCONTEXT structure: 


typedef struct _CONVCONTEXT /* cctxt */ 
{ 

ULONG cb; 

ULONG fsContext; 

ULONG idCountry; 

ULONG usCodepage; 

ULONG usLangID; 

ULONG usSubLangID; 
} CONVCONTEXT; 


cb The size of the structure, in bytes. 

fsContext Either DDECTXT_CASESENSITIVE or zero. 

idCountry Country code. 

usCodePage Code page value. 

usLangID Language identifier, or zero to indicate no language in- 
formation. 

usSubLangID Language identifier, or zero to indicate no language 
information. 


RETURNS 


The message return value. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINDDE 


SEE ALSO 
WinDdelnitiate -371, WinDdePostMsg -373 
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NOTES 


A DDE server can issue this when it receives the WM_DDE INITIATE 
message, after examining the application and topic names. If the server 
responds, the DDE client receives the WM_DDE_INITIATEACK message. 

If the client passes a zero-length application name and the 
“System” topic, the server should issue this function with its own server 
name and the “System” topic. 

If the client passes a zero-length string for the topic name and the 
server recognizes the the server name string (or it is a zero-length 
string), the server should issue this function once for each of the top- 
ics it supports. 

After a successful initiation, the conversation parties use WinDde- 
PostMsg to pass all further DDE messages. 





WinEmptyClipbrd 
Deletes everything from the clipboard and frees data. 


SYNTAX 
BOOL WinEmptyClipbrd (HAB had) 


PARAMETERS 
hab - input 
Anchor block handle. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCLIPBOARD 


SEE ALSO 


WinSetClipbrdData -383, WinOpenClipbrd -378, 
WinSetClipbrdOwner -385 


NOTES 


This function deletes all pointers from the clipboard and frees the stor- 
age they refer to. Programs should call this function before writing 
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new data to the clipboard. The program must first gain access to the 
clipboard with WinOpenClipbrd before calling this function. 

This function sends WM_DESTROYCLIPBOARD to any registered 
clipboard owner. 





® WinEnumClipbrdFmts 


Enumerates the formats on the clipboard. 


SYNTAX 
ULONG WinEnumClipbrdFmts (HAB hab, ULONG /mi) 


PARAMETERS 

hab - input 

Anchor block handle. 

fmt - input 

The previous format returned, or zero. 


RETURNS 


The next clipboard format available, or zero if none. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCLIPBOARD 


SEE ALSO 


WinQueryClipbrdFmtInfo -381, WinQueryClipbrdData -379, 
WinOpenClipbrd -378 


NOTES 


A program can call this function in a loop to determine the formats 
available on the clipboard, and exit the loop when this function re- 
turns zero. To begin the loop, pass zero for fmt. 

You must open the clipboard before issuing this function. 





@ WinOpenClipbrd 


Gains access to the clipboard. 
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SYNTAX 
BOOL WinOpenClipbrd (HAB hab) 


PARAMETERS 
hab - input 
Anchor block handle. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCLIPBOARD 


SEE ALSO 
WinCloseClipbrd -370 


NOTES 


This function gives a program access to the clipboard—PM allows only 
one program to have the clipboard open at a time. If another program 
has the clipboard open when this function is called, PM blocks the 
caller until the clipboard is closed. However, the program can still re- 
ceive messages while it is blocked. 

When the program is finished reading or writing the clipboard, it 
should call WinCloseClipbrd to release access. 





WinQueryClipbrdData 


Retrieves a pointer or handle from the clipboard. 


SYNTAX 
ULONG WinQueryClipbrdData (HAB hab, ULONG fmt) 


PARAMETERS 

hab - input 

Anchor block handle. 

fmt - input 

The format desired. This can be one of the CF_xxx system-defined for- 
mats or a private format. 
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RETURNS 


A handle or pointer, depending on the format, or zero if the format 
doesn’t exist. 


OTHER INFO 
Include file: pmwin.h Define: INGL_WINCLIPBOARD 


SEE ALSO 


WinOpenClipbrd -378, WinCloseClipbrd -370, 
WinQueryClipbrdFmtInfo -381, WinEnumClipbrdF mts -378 


NOTES 


This function retrieves a handle or a pointer from the clipboard de- 
pending on the format: 


CF_ BITMAP Bitmap handle 
CF_DSPBITMAP Pointer to memory 
CF_DSPMETAFILE Pointer to memory 
CF_DSPTEXT Pointer to memory 
CF_METAFILE Metafile handle 
CF PALETTE Palette handle 
CF_TEXT Pointer to memory 
private format Pointer to memory 


See the introduction to this chapter for a discussion of clipboard 
formats. 

Before issuing this function, the program must first gain access to 
the clipboard with WinOpenClipbrd and should call WinCloseClipbrd 
when finished. After closing the clipboard, the program cannot access 
the returned handle or pointer, since the system removes the pro- 
gram’s addressability to the handle or pointer. Therefore, the program 
must copy the data while the clipboard is open if it needs to access the 
clipboard data after the clipboard is closed. 

A program can determine if a format is available before issuing 
this function using WinQueryClipbrdFmtInfo or WinEnumClipbrd- 
Fimts. 
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@ WinQueryClipbrdFmtinfo 


Determines if a format is available. 


SYNTAX 


BOOL WinQueryClipbrdFmtInfo (HAB hab, ULONG fmt, PULONG 
pulF'milnfo) 


PARAMETERS 

hab - input 

Anchor block handle. 

fmt- input 

The clipboard format to query. This is one of the standard CF_XXX val- 
ues or a private format. See the beginning of this chapter for a de- 
scription of clipboard formats. 

pulFmtInfo - output 

Pass the address of a ULONG where this function returns the memory 
model and usage flags for the format. See WinSetClipbrdData (pg 
383) for a discussion of these flags. 


RETURNS 
TRUE if if the format exists on the clipboard, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCLIPBOARD 


SEE ALSO 


WinSetClipbrdData -383, WinQueryClipbrdData -379, 
WinEnumClipbrdF mts -378 


NOTES 


A program can use this function to determine if the clipboard holds a 
data format. Typically, a program would issue this function during the 
WM_INITMENU message and disable the Paste menu item if a suitable 
format was not available. ‘That way, the user realizes that a paste opera- 
tion is not currently possible. 

If a program has specified delayed rendering on WinSetClipbrd- 
Data, this function doesn’t send a WM_RENDERFMT message—PM 
sends that message when a program calls WinQueryClipbrdData. 
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@ WinQueryClipbrdOwner 


Retrieves the window handle of the clipboard owner. 


SYNTAX 
HWND WinQueryClipbrdOwner (HAB hab) 


PARAMETERS 
hab - input 
Anchor block handle. 


RETURNS 


The clipboard owner’s window handle, or NULLHANDLE if there is 
no owner. 


OTHER INFO 
Include file: pmwin.h Define: INGL_WINCLIPBOARD 


SEE ALSO 
WinSetClipbrdOwner -385, WinSetClipbrdData -383 


NOTES 


See WinSetClipbrdOwner for a discussion of the clipboard owner. 


@ WinQueryClipbrdViewer 





Retrieves the window handle of the clipboard viewer. 


SYNTAX 
HWND WinQueryClipbrdViewer (HAB hab) 


PARAMETERS 
hab - input 
Anchor block handle. 


RETURNS 


The clipboard viewer’s window handle, or NULLHANDLE if there is 
no current clipboard viewer. 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINCLIPBOARD 


SEE ALSO 
WinSetClipbrdViewer -386 





WinSetClipbrdData 


Writes a pointer or a handle to the clipboard. 


SYNTAX 


BOOL WinSetClipbrdData (HAB hab, ULONG ul, ULONG /mi, 
ULONG /lags) 


PARAMETERS 

hab - input 

Anchor block handle. 

ul - input 

A pointer or a handle, depending on the format. You can also pass 
NULLHANDLE to set up a delayed rendering or owner display. 

fmt- input 

The clipboard format to store. This is one of the standard CF_XXX val- 
ues or a private format. See the beginning of this chapter for a de- 
scription of clipboard formats. 

flags - input 

A combination of the following flags combinations not allowed are 
noted: 


CFI_HANDLE Specify this flag if you passed a handle in the wl argu- 
ment. Use this flag for bitmaps, metafiles, and palettes. You cannot 
combine this flag with CFL_POINTER. 

CFI_LOWNERDISPLAY = Specify this flag if you want to receive the 
WM_PAINTCLIPBRD message from the clipboard viewer. You 
should also set the u/ argument to zero. 

CFI_OWNERFREE = Specify this flag if you do not want the clipboard 
to free the storage or handle when WinEmptyClipbrd is called. It is 
then your responsibility to free the storage or handle. 
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CFILPOINTER Specify this flag if you passed an address rather than a 
handle in the u/ argument. Use this flag for text, private format, and 
the display formats. You cannot combine this flag with CFL HANDLE: 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCLIPBOARD 


SEE ALSO 


WinOpenClipbrd -378, WinCloseClipbrd -370, 
WinQueryClipbrdData -379, WinSetClipbrdOwner -385, 
WinEmptyClipbrd -377 


NOTES 


Many programs issue this function when the user selects Cut or Copy 
from the menu. 

Before calling this function, you must gain access to the clip- 
board with WinOpenClipbrd, and you should release access with 
WinCloseClipbrd when you are finished. After closing the clipboard, 
you cannot access the pointer or handle stored on the clipboard—it 
now belongs to the system and PM removes your addressability. 

If you pass a pointer to memory (CF_TEXT, private format, and 
the display formats) you must allocate the memory with DosAlloc- 
SharedMem and specify the OBJ GIVEABLE, PAG_READ, PAG_WRITE, 
and PAG_COMMIT flags. 

If the clipboard already contains data of the given format, this 
function frees the existing handle or storage. 

It’s good practice to store more than one format in the clipboard 
for each cut or copy request to increase the chances that the receiving 
program will find a format it recognizes. But since creating the data in 
multiple formats can take a long time and the majority of programs 
only request text, it seems wasteful to support all of the clipboard for- 
mats. To address this, a program can use a technique called delayed ren- 
dering, where the program writes a NULLHANDLE to the clipboard in- 
stead of a pointer or a handle. This in effect is a promise to provide the 
data only if a program requests it. 

If you pass NULLHANDLE for the handle or pointer, you should 
also call WinSetClipbrdOwner to make yourself the clipboard owner. 
Then PM will send you the WM_RENDERFMT message when a pro- 
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gram attempts to read the pointer or handle from the clipboard. In 
WM_RENDERFMT you should issue WinSetClipbrdData again, this 
time passing the actual pointer or handle. Note: Do not open the clip- 
board in the WM_RENDERFMT processing. PM will also send the clip- 
board owner the WM_DESTROYCLIPBRD message if WinEmpty- 
Clipbrd is called. ‘The clipboard owner can then delete the saved data. 





WinSetClipbrdOwner 


Assigns the clipboard owner. 


SYNTAX 
BOOL WinSetClipbrdOwner (HAB hab, HWND hwnd) 


PARAMETERS 

hab - input 

Anchor block handle. 

hwnd - input 

The window handle of the new clipboard owner, or NULLHANDLE to 
cease being the clipboard owner. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCLIPBOARD 


SEE ALSO 
WinSetClipbrdData -383, WinQueryClipbrdOwner -382 


NOTES 


Typically a program becomes the clipboard owner to provide a delayed 
rendering, as described in WinSetClipbrdData. The clipboard owner 
may receive the following messages: 


WM_DESTROYCLIPBOARD Indicates the clipboard owner can 
free storage or handles. 

WM_HSCROLLCLIPBOARD The clipboard viewer requests the 
owner to scroll the viewer’s window. 
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WM_PAINTCLIPBOARD The clipboard viewer requests the owner 
to draw to the viewer’s window. 

WM_RENDERALLFMTS The clipboard owner receives this message 
if it is closed so it can write the delayed data to the clipboard before 
exiting. 

WM_RENDERFMT A program requested the delayed format. 

WM_SIZECLIPBOARD The clipboard viewer was sized. ‘The owner 
can store the size for future painting. 

WM_VSCROLLCLIPBOARD The clipboard viewer requests the 
owner to scroll the viewer’s window. 





@ WinSetClipbrdViewer 


Assigns the clipboard viewer. 


SYNTAX 
BOOL WinSetClipbrdViewer (HAB hab, HWND hwnd) 


PARAMETERS 

hab - input 

Anchor block handle. 

hwnd - input 

The new clipboard viewer, or NULLHANDLE to cease being the clip- 
board viewer. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCLIPBOARD 


SEE ALSO 


WinQueryClipbrdViewer -382, WinOpenClipbrd -378, 
WinCloseClipbrd -370 
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NOTES 


A clipboard viewer is a program that shows the user the current con- 
tents of the clipboard. The clipboard viewer receives the WM_DRAW- 
CLIPBOARD message whenever new data is written to the clipboard. 

You must gain access to the clipboard with WinOpenClipbrd be- 
fore issuing this function and close it when you are finished. 
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Sin every Presentation Manager window is a rectangle, manipulat- 
ing rectangles is a common operation in PM programs. PM pro- 
vides the functions described in this chapter so that programs can 
work with rectangles. 


What Is a Rectangle? 


Many of the functions in this chapter use the RECT data type defined 
in OS2DEF.H: 


<typedef struct 

{ 
LONG xLeft; 
LONG yBottom; 
LONG xRight; 
LONG yTop; 

} RECT; 


xLeft The left x-coordinate of the rectangle. 
yBottom The bottom y-coordinate of the rectangle. 
xRight The right x-coordinate of the rectangle. 
ylop The top y-coordinate of the rectangle. 
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Rectangle Functions 





WinCopyRect copies the coordinates from one rectangle to another 
(pg 389). 

WinEqualRect determines if two rectangles are the same (pg 390). 
WinInflateRect expands or shrinks a rectangle (pg 391). 
WinIntersectRect returns a rectangle containing the intersection of 
two rectangles (pg 392). 

WinIsRectEmpty determines if a rectangle has nonzero width and 
height (pg 393). 

WinMakeRect converts a window rectangle to a graphics rectangle (pg 
D4). 

WinOffsetRect moves a rectangle (pg 395). 

WinPtInRect determines if a point falls inside of a rectangle (pg 395). 
WinSetRect initializes a rectangle (pg 396). 

WinSetRectEmpty initializes a rectangle to zero width and height (pg 
B97). 

WinSubtractRect subtracts one rectangle from another and returns 
the result (pg 398). 

WinUnionRect returns a rectangle containing the union of two rec- 


tangles (pg 399). 





@ WinCopyRect 


Copies the coordinates from one rectangle to another. 


SYNTAX 
BOOL WinCopyRect (HAB hab, PRECTL prclDest, PRECTL prelSrc) 


PARAMETERS 

hab - input 

Anchor block handle. 

prelDest - output 

Pass the address of a RECTL structure. This function copies the con- 
tents of prelSrc to prelDest. 

prelSre - input 

Pass the address of a RECTL structure. 
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RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINRECTANGLES 


SEE ALSO 


WinEqualRect -390, WinInflateRect -391, WinIntersectRect -392, 
WinIsRectEmpty -393, WinMakeRect -394, WinOffsetRect -395, 
WinPtInRect -395, WinSetRect -396, WinSetRectEmpty -397, 
WinSubtractRect -398, WinUnionRect -399 


NOTES 
The coordinates in the rectangles must be between —32768 and 32767. 





@ WinEqualRect 


Determines if two rectangles are the same. 


SYNTAX 
BOOL WinkqualRect (HAB hab, PRECTL prcll, PRECTL prcl2) 


PARAMETERS 

hab - input 

Anchor block handle. 

prell - input 

Pass the address of a RECTL structure. 
prel2 - input 

Pass the address of a RECTL structure. 


RETURNS 


TRUE if the rectangles are the same, FALSE otherwise or if an error 
occurred. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINRECTANGLES 
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SEE ALSO 


WinCopyRect -389, WinInflateRect -391, WinIntersectRect -392, 
WinIsRectEmpty -393, WinMakeRect -394, WinOffsetRect -395, 
WinPtInRect -395, WinSetRect -396, WinSetRectEmpty -397, 
WinSubtractRect -398, WinUnionRect -399 


NOTES 


This function returns TRUE if both rectangles are empty, even if they 
have different coordinates. An empty rectangle is one where the width 
and height are both zero. 

The coordinates in the rectangles must be between —32768 and 


32767. 





WinlnflateRect 





Expands or shrinks a rectangle. 


SYNTAX 
BOOL WinInflateRect (HAB hab, PRECTL prcl, LONG cx, LONG cy) 


PARAMETERS 

hab - input 

Anchor block handle. 

prel - input/output 

Pass the address of a RECTL structure. This modifies the coordinates 
in this rectangle. 

cx - input 

One half of the amount to expand the rectangle’s width. 

cy - input 

One half of the amount to expand the rectangle’s height. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINRECTANGLES 
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SEE ALSO 


WinCopyRect -389, WinEqualRect -390, WinIntersectRect -392, 
WinIsRectEmpty -393, WinMakeRect -394, WinOffsetRect -395, 
WinPtInRect -395, WinSetRect -396, WinSetRectEmpty -397, 
WinSubtractRect -398, WinUnionRect -399 


NOTES 


This function subtracts cx from the left side of the rectangle and adds 
cx to the right side. It also subtracts cy from the bottom side and adds 
cy to the top side. Note that cx and/or cy can be negative to shrink the 
rectangle. 

The coordinates in the rectangle must be between —32768 and 


32767. 





@ WinlntersectRect 





Returns a rectangle containing the intersection of two rectangles. 


SYNTAX 

BOOL WinIntersectRect (HAB hab, PRECTL prcelDest, PRECTL prcl1, 
PRECTL prcl2) 

PARAMETERS 

hab - input 

Anchor block handle. 


prelDest - output 

Pass the address of a RECTL structure. This function initializes this rec- 
tangle to the intersection of prell and prclz. 

prell - input 

Pass the address of a RECTL structure. 

prel2 - input 

Pass the address of a RECTL structure. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINRECTANGLES 


Rectangles 393 


SEE ALSO 


WinCopyRect -389, WinEqualRect -390, WinInflateRect -391, 
WinIsRectEmpty -393, WinMakeRect -394, WinOffsetRect -395, 
WinPtInRect -395, WinSetRect -396, WinSetRectEmpty -397, 
WinSubtractRect -398, WinUnionRect -399 


NOTES 


This function calculates the intersection of prell and prcl2 and returns 
the coordinates in prelDest. If the two input rectangles do not intersect, 
this function returns an empty rectangle. The program can determine 
if the rectangle is empty win WinIsRectEmpty. 

The coordinates in the rectangle must be between —32768 and 


32767. 





WinlsRectEmpty 


Determines if a rectangle has nonzero width and height. 


SYNTAX 
BOOL WinlsRectEmpty (HAB hab, PRECTL prcl) 


PARAMETERS 

hab - input 

Anchor block handle. 

prel - input 

Pass the address of a RECTL structure. 
RETURNS 


TRUE if rectangle has zero width and height, FALSE otherwise or if an 
error occurred. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINRECTANGLES 


SEE ALSO 


WinCopyRect -389, WinEqualRect -390, WinInflateRect -391, 
WinIntersectRect -392, WinMakeRect -394, WinOffsetRect -395, 
WinPtInRect -395, WinSetRect -396, WinSetRectEmpty -397, 
WinSubtractRect -398, WinUnionRect -399 
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NOTES 


A rectangle is empty if the left and right sides are the same and the top 
and bottom sides are the same. 
The coordinates in the rectangle must be between —32768 and 


S216, 





WinMakeRect 





Converts a window rectangle to a graphics rectangle. 


SYNTAX 
BOOL WinMakeRect (HAB hab, PWRECT pwc!) 


PARAMETERS 

hab - input 

Anchor block handle. 

purel - input/output 

Pass the address of a WRECT structure. This function converts the 
WRECT to a RECTL. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINRECTANGLES 


SEE ALSO 


WinCopyRect -389, WinEqualRect -390, WinInflateRect -391, 
WinIntersectRect -392, WinIsRectEmpty -393, WinOffsetRect -395, 
WinPtInRect -395, WinSetRect -396, WinSetRectEmpty -397, 
WinSubtractRect -398, WinUnionRect -399 


NOTES 


In C or C++ this function is unnecessary because WRECT and RECTL 
are the same. 
The coordinates in the rectangle must be between -32768 and 


32767. 
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WinOffsetRect 





Moves a rectangle. 


SYNTAX 
BOOL WinOffsetRect (HAB hab, PRECTL prcl, LONG x, LONG y) 


PARAMETERS 

hab - input 

Anchor block handle. 

prel - input/output 

Pass the address of a RECTL structure. This function adds x to the left 
and right sides and adds y to the top and bottom sides. 

x - input 

The amount to move the rectangle horizontally. 

y- input 

The amount to move the rectangle vertically. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINRECTANGLES 


SEE ALSO 


WinCopyRect -389, WinEqualRect -390, WinInflateRect -391, 
WinIntersectRect -392, WinIsRectEmpty -393, WinMakeRect -394, 
WinPtInRect -395, WinSetRect -396, WinSetRectEmpty -397, 
WinSubtractRect -398, WinUnionRect -399 


NOTES 
The coordinates in the rectangle must be between —32768 and 32767. 





WinPtinRect 





Determines if a point falls inside of a rectangle. 
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SYNTAX 
BOOL WinPtInRect (HAB hab, PRECTL prcl, PPOINTL ppil) 


PARAMETERS 

hab - input 

Anchor block handle. 

prel - input 

Pass the address of a RECTL structure. 
pptl - input 

Pass the address of a POIJNTL structure. 


RETURNS 


TRUE if the point falls within the rectangle, FALSE otherwise or if an 
error occurred. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINRECTANGLES 


SEE ALSO 


WinCopyRect -389, WinEqualRect -390, WinInflateRect -391, 
WinIntersectRect -392, WinIsRectEmpty -393, WinMakeRect -394, 
Win OffsetRect -395, WinSetRect -396, WinSetRectEmpty -397, 
WinSubtractRect -398, WinUnionRect -399 


NOTES 
The coordinates in the rectangle must be between —32768 and 32767. 





@ WinSetRect 





Initializes a rectangle. 


SYNTAX 


BOOL WinSetRect (HAB hab, PRECTL prcl, LONG [Lefit, LONG 
[Bottom, LONG [Right, LONG [Top) 


PARAMETERS 
hab - input 
Anchor block handle. 
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prel- output 

Pass the address of a RECTL structure. This function initializes the co- 
ordinates in this rectangle. 

[Left - input 

The left coordinate of the rectangle. 
[Bottom - input 

The bottom coordinate of the rectangle. 
IRight - input 

The right coordinate of the rectangle. 
[Top - input 

The top coordinate of the rectangle. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINRECTANGLES 


SEE ALSO 


WinCopyRect -389, WinEqualRect -390, WinInflateRect -391, 
WinIntersectRect -392, WinIsRectEmpty -393, WinMakeRect -394, 
Win OffsetRect -395, WinPtInRect -395, WinSetRectEmpty -397, 
WinSubtractRect -398, WinUnionRect -399 


NOTES 
The coordinates in the rectangle must be between —32768 and 32767. 





WinSetRectEmpty 


Initializes a rectangle to zero width and height. 


SYNTAX 
BOOL WinSetRectEmpty (HAB hab, PRECTL prc!) 


PARAMETERS 
hab - input 
Anchor block handle. 
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prel - output 
Pass the address of a RECTL structure. This function initializes all of 
the coordinates in this rectangle to zero. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINRECTANGLES 


SEE ALSO 


WinCopyRect -389, WinEqualRect -390, WinInflateRect -391, 
WinIntersectRect -392, WinIsRectEmpty -393, WinMakeRect -394, 
WinOffsetRect -395, WinPtInRect -395, WinSetRect -396, 
WinSubtractRect -398, WinUnionRect -399 





@ WinSubtractRect 





Subtracts one rectangle from another and returns the result. 


SYNTAX 

BOOL WinSubtractRect (HAB hab, PRECTL prelDest, PRECTL prclJ, 
PRECTL prcl2) 

PARAMETERS 

hab - input 

Anchor block handle. 


prelDest - output 

Pass the address of a RECTL structure. This function subtracts prel2 
from prcll and returns the result in this rectangle. 

prell - input 

Pass the address of a RECTL structure. 

prel2 - input 

Pass the address of a RECTL structure. 


RETURNS 


TRUE if the resulting rectangle is not empty, FALSE otherwise or if an 
error occurred. 
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OTHER INFO 
Include file: pmwin.h Define: INCL_WINRECTANGLES 


SEE ALSO 


WinCopyRect -389, WinEqualRect -390, WinInflateRect -391, 
WinIntersectRect -392, WinIsRectEmpty -393, WinMakeRect -394, 
WinOffsetRect -395, WinPtInRect -395, WinSetRect -396, 
WinSetRectEmpty -397, WinUnionRect -398 


NOTES 


If the subtraction doesn’t result in a valid rectangle, this function re- 
turns prell in prcelDest. 
The coordinates in the rectangle must be between —32768 and 


32767. 





WinUnionRect 





Returns a rectangle containing the union of two rectangles. 


SYNTAX 

BOOL WinUnionRect (HAB hab, PRECTL prelDest, PRECTL prelJ, 
PRECTL prel2) 

PARAMETERS 

hab - input 

Anchor block handle. 


prelDest - output 

Pass the address of a RECTL structure. This function initializes this rec- 
tangle to the union of prell and prcl2. The output rectangle will bound 
the two input rectangles. 

prell - input 

Pass the address of a RECTL structure. 

prel2 - input 

Pass the address of a RECTL structure. 


RETURNS 


TRUE if the resulting rectangle is nonempty, FALSE otherwise or if an 
error occurred. 


400 OS/2 WARP Presentation Manager API 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINRECTANGLES 


SEE ALSO 


WinCopyRect -389, WinEqualRect -390, WinInflateRect -391, 
WinIntersectRect -392, WinIsRectEmpty -393, WinMakeRect -394, 
Win OffsetRect -395, WinPtInRect -395, WinSetRect -396, 
WinSetRectEmpty -397, WinSubtractRect -398 


NOTES 
The coordinates in the rectangle must be between —32768 and 32767. 





els 
Task List Functions 








enever the user presses Ctrl-Esc, Presentation Manager displays 

a list of programs called the task list, which lets the user change 

to a new task, close a task, and so on. This chapter documents the PM 
functions to manipulate the task list. 

Actually, “task list” is somewhat of a misnomer, as the list really 
consists of windows. A program can add one or more of its windows’ ti- 
tles to the list, but since it’s optional, running programs can be omit- 
ted from the list. 


OS/2 |.x Compatibility 


Some of the task list functions and structures were designed for the 
OS/2 1.x user-interface shell, and are obsolete in the OS/2 2.x Work- 
place Shell. For example, the 1.x shell supported Program Groups on 
the desktop, which contained references to programs. The Workplace 
Shell replaces Program Groups with Folders containing program ob- 
jects. 

Nevertheless, for upward compatibility, some the of the functions 
and structures still reference the 1.x usage. These anachronisms will be 
described in the text, but new programs should use the 2.x techniques 
instead. 
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Task List Functions 





WinAddSwitchEntry adds an entry to the task list (pg 402). 
WinChangeSwitchEntry modifies an entry in the task list (pg 404). 
WinCreateSwitchEntry adds an entry to the task list (pg 407). 
WinQuerySessionTitle retrieves a task list entries’ text string (pg 409). 
WinQuerySwitchEntry retrieves information about a task list entry (pg 
410). 

WinQuerySwitchHandle queries a task list entries’ handle (pg 412). 
WinQuerySwitchList retrieves information about the entries in the 
task list (pg 413). 

WinQueryTaskSizePos retrieves the size and position of the next win- 
dow to be created (pg 416). 

WinQueryTaskTitle retrieves a task list entries’ text string (pg 418). 
WinRemoveSwitchEntry removes an entry from the task list (pg 418). 
WinStartApp executes a program (pg 419). 

WinSwitchToProgram changes the active task (pg 423). 
WinTerminateApp terminates a program started with WinStartApp 
(pg 424). 





WinAddSwitchEntry 


Adds an entry to the task list. 


SYNTAX 
HSWITCH WinAddSwitchEntry(PSWCNTRL pswcil) 


PARAMETERS 
pswetl - input 
Pass the address of an SWCNTARL structure: 


#define MAXNAMEL 60 


typedef struct _SWCNTRL /* sweel */ 
{ 

HWND hwnd; 

HWND hwndIcon; 


HPROGRAM hprog; 


PID 1dProcess; 
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ULONG idSession; 
ULONG uchVisibility; 
ULONG EbJump ; 
CHAR szSwtitle [MAXNAMEL+4]; 
ULONG bProgType; 
} SWCNTRL; 


hwnd ‘The handle of the window corresponding to the task list entry. 
hwndicon The program’s icon (not used in OS/2 2.x; set to NULL- 
HANDLE). 
hprog The handle of the program’s group (not used in OS/2 2.x; set 
to NULLHANDLE). 
idProcess The identifier of the OS/2 process that owns the window. 
You can retrieve the process identifier with WinQueryWindow- 
Process. 
idSession ‘The identifier of the OS/2 session that owns the window. 
uchVisibility One of the following values: 
SWL_GRAYED Same as SWL_INVISIBLE. 
SWL_INVISIBLE ‘Text doesn’t appear in task list. 
SWL_VISIBLE Text appears in task list. 
fbJump One of the following values: 
SWL_JUMPABLE User can select the program using the Alt-Tab cy- 
cle, 
SWL_NOTJUMPABLE User cannot select the program using the 
Alt-Tab cycle. 
szSwtitle The text string for the task list entry. Note that this is a 
string, not a string pointer. 
bProgType One of the following values: 
PROG_DEFAULT PM determines program type. 
PROG_FULLSCREEN OS/2 program that runs in a full-screen 
session. 
PROG PM Presentation Manager program. 
PROG_VDM_ DOS or Windows program that runs in a full-screen 
session. 
PROG _WINDOWABLEVIO OS/2 program that runs in a win- 
dowed session. 
PROG WINDOWEDVDM_ DOS or Windows program that runs in 
a windowed session. 


RETURNS 


The switch entry handle if successful, NULLHANDLE otherwise. 
Possible returns from WinGetLastError: 
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OX1201 - PMERR NO_SPACE 

OX1202 - PMERR_INVALID_SWITCH_HANDLE 
0X1204 - PMERR_ INVALID PROCESS_ID 
0X1206 - PMERR_ INVALID WINDOW 

0OX1208 - PMERR_INVALID PARAMETERS 
0X1209 - PMERR_ INVALID _PROGRAM_TYPE 
OX120B - PMERR_INVALID_SESSION_ID 


OTHER INFO 
Include file: pmshl.h Define: INCL_WINSWITCHLIST 


SEE ALSO 


WinCreateSwitchEntry -407, WinQuerySwitchEntry -410, 
WinRemoveSwitchEntry -418, WinCreateStdWindow -17 


NOTES 


This function is equivalent to WinCreateSwitchEntry. 

Normally, programs add their main window’s title to the task list, 
but do not add to secondary windows. Also, programs normally specify 
a frame window handle as the swetl.hwnd argument. 

Note that if you create a standard window with the FCF_TASKLIST 
flag, you don’t need to issue WinAddSwitchEntry to add the text to the 
task list—WinCreateStdWindow sets the title bar text and the task list 
text. Furthermore, since the frame “remembers” the FCF_TASKLIST 
flag as a style (FS_TASKLIST), whenever you call WinSetWindowText 
on the frame window handle, that function changes both the standard 
window title bar text and the task list text. 





WinChangeSwitchEntry 


Modifies an entry in the task list. 


SYNTAX 

ULONG WinChangeSwitchEntry (HSWITCH hswitch, PSWCNTRL 
pswetl) 

PARAMETERS 


hswitch - input 
The task list handle returned by WinAddSwitchEntry, WinCreateSwitch- 
Entry, WinQuerysSwitchList, or WinQuerysSwitchEntry. 
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pswetl - input 
Pass the address of an SWCNTRL structure: 


#define MAXNAMEL 60 


typedef struct _SWCNTRL /* swetl */ 
{ 

HWND hwnd; 

HWND hwndIcon; 


HPROGRAM hprog; 
PID 1dProcess; 
ULONG idSession; 
ULONG uchVisibility; 
ULONG fbJump; 
CHAR szSwtitle [MAXNAMEL+4] ; 
ULONG bProgType; 
} SWCNTRL; 


hwnd The handle of the window corresponding to the task list entry. 
hwndicon The program’s icon (not used in OS/2 2.x; set to NULL- 
HANDLE). 
hprog The handle of the program’s group (not used in OS/2 2.x; set 
to NULLHANDLE). 
idProcess ‘The identifier of the OS/2 process that owns the window. 
You can retrieve the process identifier with WinQueryWindow- 
Process. 
idSession ‘The identifier of the OS/2 session that owns the window. 
uchVisibility One of the following values: 
SWL_ GRAYED Same as SWL_JINVISIBLE. 
SWL_INVISIBLE ‘Text doesn’t appear in task list. 
SWL_VISIBLE ‘Text appears in task list. 
fbJump One of the following values: 
SWL_JUMPABLE User can select the program using the Alt-Tab 
cycle. 
SWL_NOTJUMPABLE User cannot select the program using the 
Alt-Tab cycle. 
szSwtitle ‘The text string for the task list entry. Note that this is a 
string, not a string pointer. 
bProgType One of the following values: 
PROG_DEFAULT PM determines program type. 
PROG FULLSCREEN OS/2 program that runs in a full-screen 
session. 


406 OS/2 WARP Presentation Manager API 


PROG _PM Presentation Manager program. 

PROG_VDM_ DOS or Windows program that runs in a full screen 
session. 

PROG _WINDOWABLEVIO OS/2 program that runs in a win- 
dowed session. 

PROG_WINDOWEDVDM_ DOS or Windows program that runs in 
a windowed session. 


RETURNS 


Zero if successful, nonzero otherwise. 
Possible returns from WinGetLastError: 


OX1201 - PMERR NO_SPACE 

OX1202 - PMERR_ INVALID _SWITCH_HANDLE 
OX1204 - PMERR INVALID _PROCESS_ID 
0OX1206 - PMERR INVALID WINDOW 

OX1208 - PMERR_ INVALID PARAMETERS 
0X1209 - PMERR INVALID _PROGRAM_TYPE 
OX120B - PMERR_INVALID_SESSION_ID 


OTHER INFO 
Include file: pmshl.h Define: INCL_WINSWITCHLIST 


SEE ALSO 


WinAddSwitchEntry -402, WinCreateSwitchEntry -407, 
WinQueryswitchList -413, WinQuerySwitchEntry -410, 
WinQueryWindowProcess -292 


NOTES 


You can use this function to change the internal switch entry record 
that PM maintains for all switch list entries. It’s often used to change 
the switch list title; for example, when a word processor opens a new 
file, it can change its title bar text and the switch list entry to reflect the 
new file name. Note that if you create a standard window with the 
FCF_TASKLIST flag, you don’t need to issue WinChangeSwitchEntry 
to change the task list text; instead, you can call WinSetWindowText on 
the frame window handle—that function changes both the standard 
window title bar text and the task list text. 

If you want to change only a few fields in the structure, it’s recom- 
mended to first initialize the structure with WinQuerySwitchEntry, 
modify the fields, then issue this function to update the switch entry. 
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® WinCreateSwitchEntry 


Adds an entry to the task list. 


SYNTAX 
HSWITCH WinCreateSwitchEntry(HAB hab, PSWCNTRL pswcil) 


PARAMETERS 

hab - input 

Anchor block handle. 

pswetl - input 

Pass the address of an SWCNTRL structure: 


#define MAXNAMEL 60 


typedef struct _SWCNTRL /*® ewetl */ 
{ 

HWND hwnd; 

HWND hwndiIcon; 


HPROGRAM hprog; 


PID idProcess; 
ULONG idSession; 
ULONG uchVisibility; 
ULONG fbJump ; 
CHAR szSwtitle [MAXNAMEL+4]; 
ULONG bProgType; 
} SWCNTRL; 


hwnd The handle of the window corresponding to the task list entry. 
hwndIcon The program’s icon (not used in OS/2 2.x; set to NULL- 
HANDLE). 
hprog The handle of the program’s group (not used in OS/2 2.x; set 
to NULLHANDLE). 
idProcess ‘The identifier of the OS/2 process that owns the window. 
You can retrieve the process identifier with WinQueryWindow- 
Process. 
idSession ‘The identifier of the OS/2 session that owns the window. 
uchVisibility One of the following values: 
SWL_GRAYED Same as SWL_JINVISIBLE. 
SWL_INVISIBLE ‘Text doesn’t appear in task list. 
SWL_VISIBLE ‘Text appears in task list. 
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fbJump One of the following values: 
SWL_JUMPABLE User can select the program using the Alt-Tab 
cycle. 
SWL_NOTJUMPABLE User cannot select the program using the 
Alt-Tab cycle. 
szSwtitle The text string for the task list entry. Note that this is a 
string, not a string pointer. 
bProgType One of the following values: 
PROG _ DEFAULT PM determines program type. 
PROG FULLSCREEN OS/2 program that runs in a full-screen 
session. 
PROG_PM Presentation Manager program. 
PROG_VDM_ DOS or Windows program that runs in a full-screen 
session. 
PROG_WINDOWABLEVIO OS/2 program that runs in a win- 
dowed session. 
PROG_WINDOWEDVDM_ DOS or Windows program that runs in 
a windowed session. 


RETURNS 
The switch entry handle if successful, NULLHANDLE otherwise. 
Possible returns from WinGetLastError: 


OX1201 - PMERR NO_SPACE 

0OX1202 - PMERR_ INVALID SWITCH_HANDLE 
OX1204 - PMERR_ INVALID _PROCESS_ID 
0X1206 - PMERR_ INVALID WINDOW 

0X1208 - PMERR_ INVALID PARAMETERS 
0X1209 - PMERR_ INVALID _PROGRAM_TYPE 
0X120B - PMERR_ INVALID _SESSION_ID 


OTHER INFO 
Include file: pmshl.h Define: INCL_WINSWITCHLIST 


SEE ALSO 


WinAddSwitchEntry -402, WinQuerySwitchEntry -410, 
WinRemoveSwitchEntry -418, WinCreateStdWindow -17 


NOTES 
This function is equivalent to WinAddSwitchEntry. 
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Normally, programs add their main window’s title to the task list, 
but do not add secondary windows. Also, programs normally specify a 
frame window handle as the swetl.hwnd argument. 

Note that if you create a standard window with the FCF_TASKLIST 
flag, you don’t need to issue WinAddSwitchEntry to add the text to the 
task list; WinCreateStdWindow sets the title bar text and the task list 
text. Furthermore, since the frame “remembers” the FCF_TASKLIST 
flag as a style (FS_TASKLIST), whenever you call WinSetWindowText 
on the frame window handle, that function changes both the standard 
window title bar text and the task list text. 





WinQuerySessionT itle 


Retrieves a task list entry’s text string. 


SYNTAX 

ULONG WinQuerySessionTitle (HAB hab, ULONG uwlSession, PSZ psz, 
ULONG cb) 

PARAMETERS 

hab - input 

Anchor block handle. 


ulSession - input 

Pass an OS/2 session identifier or 0 to specify the caller’s session. 
psz- output 

Pass the address of a string that this function fills in. 

cb - input 

The string’s length. 


RETURNS 


Zero if successful, nonzero otherwise. 
Possible returns from WinGetLastError: 


OX1208 - PMERR_ INVALID PARAMETERS 
OX120B - PMERR_INVALID_SESSION_ID 


OTHER INFO 
Include file: pmshl.h Define: INCL_WINSWITCHLIST 
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SEE ALSO 
WinQueryswitchEntry -410 


NOTES 


This function is useful if you know a program’s session identifier, and 
require its task list text. 





@® WinQuerySwitchEntry 


Retrieves information about a task list entry. 


SYNTAX 

ULONG WinQuerySwitchEntry(HSWITCH  hswitch, PSWCNTRL 
pswetl) 

PARAMETERS 


hswitch - input 

The task list handle returned by WinAddSwitchEntry, WinCreate- 
SwitchEntry, WinQuerySwitchList, or WinQuerySwitchEntry. 

pswetl - output 

Pass the address of an SWCNTRL structure: 


#define MAXNAMEL 60 


typedef struct _SWCNTRL /* swetl */ 
HWND hwnd; 
HWND hwndicon; 


HPROGRAM hprog; 


PID i1dProcess; 

ULONG idSession; 

ULONG uchVisibility; 

ULONG fbJump; 

CHAR szSwtitle [MAXNAMEL+4] ; 


ULONG bProgType; 
} SWCNTRL; 


hwnd The handle of the window corresponding to the task list entry. 

hwndIcon The program’s icon (not used in OS/2 2.x; set to NULL- 
HANDLE). 

hprog The handle of the program’s group (not used in OS/2 2.x; set 
to NULLHANDLE). 
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idProcess ‘The identifier of the OS/2 process that owns the window. 
You can retrieve the process identifier with WinQueryWindow- 
Process. 
idSession ‘The identifier of the OS/2 session that owns the window. 
uchVisibility One of the following values: 
SWL_ GRAYED Same as SWL_ INVISIBLE. 
SWL_INVISIBLE ‘Text doesn’t appear in task list. 
SWL_VISIBLE Text appears in task list. 
fbJump One of the following values: 
SWL_JUMPABLE User can select the program using the Alt-Tab 
cycle. 
SWL_NOTJUMPABLE User cannot select the program using the 
Alt-Tab cycle. 
szSwtitle ‘The text string for the task list entry. Note that this is a 
string, not a string pointer. 
bProgType One of the following values: 
PROG_DEFAULT PM determines program type. 
PROG FULLSCREEN OS/2 program that runs in a full-screen 
session. 
PROG_PM Presentation Manager program. 
PROG_VDM_ DOS or Windows program that runs in a full screen 
session. 
PROG_WINDOWABLEVIO OS/2 program that runs in a win- 
dowed session. 
PROG _WINDOWEDVDM_ DOS or Windows program that runs in 
a windowed session. 


RETURNS 


Zero if successful, nonzero otherwise. 
Possible returns from WinGetLastError: 


OX1201 - PMERR_ NO_SPACE 

OX1202 - PMERR_ INVALID _SWITCH_HANDLE 
OX1204 - PMERR_ INVALID_PROCESS_ID 
0X1206 - PMERR_INVALID_WINDOW 

0X1208 - PMERR_INVALID PARAMETERS 
0X1209 - PMERR_INVALID PROGRAM_TYPE 
OX120B - PMERR_INVALID_SESSION_ID 


OTHER INFO 
Include file: pmshl.h Define: INCL_WINSWITCHLIST 
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SEE ALSO 


WinAddSwitchEntry -402, WinCreateSwitchEntry -407, 
WinQuerysSwitchList -413, WinQueryWindowProcess -292 





@ WinQuerySwitchHandle 


Queries a task list entry’s handle. 


SYNTAX 
HSWITCH WinQuerysSwitchHandle (HWND hwnd, PID pid) 


PARAMETERS 

hwnd - input 

The handle of the window that has an entry in the task list. Normally a 
frame window, if the program is a PM program. You can pass NULL- 
HANDLE if you specify a process identifier in the pid argument. 

pid - input 

The identifier of a process that has an entry in the task list. You can 
pass zero if you specify a window handle in the hwnd argument. 


RETURNS 


The switch handle, or zero if an error occurred. 
Possible returns from WinGetLastError: 


0X1204 - PMERR INVALID PROCESS ID 
0OX1206 - PMERR INVALID WINDOW 
0X1208 - PMERR_ INVALID PARAMETERS 


OTHER INFO 
Include file: pmshl.h Define: INCL_WINSWITCHLIST 


SEE ALSO 


WinQuerysSwitchEntry -410, WinRemoveSwitchEntry -418, 
WinQueryWindowProcess -292 


NOTES 


You can use the returned switch handle on other task list functions. 
If you specify both a window handle and a process identifier, they 
must both be correct. 
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@ WinQuerySwitchList 


Retrieves information about the entries in the task list. 


SYNTAX 

ULONG WinQuerySwitchList(HAB hab, PSWBLOCK pswblk, 
ULONG cd) 

PARAMETERS 

hab - input 

Anchor block handle. 


pswblk - output 

Pass the address of an SWBLOCK structure that this structure will fill, 
or pass NULL to query the number of switch entries. The SWBLOCK 
structure consists of a count header, followed by an array of SWENTRY 
structures: 


typedef struct _SWBLOCK /* swolk */ 
{ 

ULONG cswentry; 

SWENTRY aswentry[1]; 
} SWBLOCK; 


cswentry The number of SWENTRY structures that follow. 
aswnentry ‘The array of SWENTRY structures. 


Each SWENTRY structure contains the following fields: 


typedef struct _SWENTRY /* gswent */7 
{ 

HSWITCH hswitch; 

SWCNTRL swctl; 
} SWENTRY; 


hswitch ‘The entry’s switch handle. 
swetl ‘The entry’s switch data structure. 


The SWCNTRL structure contains the following fields: 
#define MAXNAMEL 60 
typedef struct _SWCNTRL /* swetl */ 


{ 
HWND hwnd; 
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HWND hwndiIcon; 
HPROGRAM hprog; 


PID idProcess; 
ULONG idSession; 
ULONG ueghVieibilicy; 
ULONG fbJump ; 
CHAR szSwtitle [MAXNAMEL+4] ; 
ULONG bProgType; 
} SWCNTRL; 


hwnd The handle of the window corresponding to the task list entry. 
hwndicon ‘The program’s icon (not used in OS/2 2.x; set to NULL- 
HANDLE). 
hprog The handle of the program’s group (not used in OS/2 2.x; set 
to NULLHANDLE). 
idProcess ‘The identifier of the OS/2 process that owns the window. 
You can retrieve the process identifier with WinQueryWindow- 
Process. 
idSession ‘The identifier of the OS/2 session that owns the window. 
uchVisibility One of the following values: 
SWL_GRAYED Same as SWL_INVISIBLE. 
SWL_INVISIBLE ‘Text doesn’t appear in task list. 
SWL_VISIBLE Text appears in task list. 
fbJump One of the following values: 
SWL_JUMPABLE User can select the program using the Alt-Tab 
cycle. 
SWL_NOTJUMPABLE User cannot select the program using the 
Alt-Tab cycle. 
szSwtitle The text string for the task list entry. Note that this is a 
string, not a string pointer. 
bProgType One of the following values: 
PROG_DEFAULT PM determines program type. 
PROG_FULLSCREEN OS/2 program that runs in a full-screen 
session. 
PROG_PM Presentation Manager program. 
PROG_VDM_ DOS or Windows program that runs in a full-screen 
session. 
PROG_WINDOWABLEVIO OS/2 program that runs in a win- 
dowed session. 
PROG_WINDOWEDVDM_ DOS or Windows program that runs in 
a windowed session. 
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cb - input 

Pass the number of bytes in the output memory buffer pointed to by 
pswhlk. Note that this is a byte count, not the number of entries in the 
array. 


RETURNS 
The number of entries returned, or zero if an error occurred. 


Possible returns from WinGetLastError: 


OX1201 - PMERR_NO_SPACE 
0X1208 - PMERR_ INVALID PARAMETERS 


OTHER INFO 
Include file: pmshl.h Define: INCL_WINSWITCHLIST 


SEE ALSO 


WinAddSwitchEntry -402, WinCreateSwitchEntry -407, 
WinQueryswitchHandle -412, WinQueryTaskTitle -418 


NOTES 


This function returns information about all of the entries in the task 
list, even invisible ones (see the swetl.uchVisibility flag in WinAddSwitch- 
Entry). Therefore, the information retrieved may contain entries that 
the user does not see in the task list. 


EXAMPLE 


The following example queries all of the switch entries and displays 
them to standard output: 


ULONG cs // switch-list entry count 

ULONG ch; // bytes of storage count 

PSWBLOCK D; // returned from WinQuerySwitchList 
int 2.3 // loop counter 


// first determine number of switch list entries 
c = WinQuerySwitchList ( hab, NULL, 0 ); 
// allocate memory for array of SWENTRYs plus the count field 
// in the SWBLOCK structure 
cb = sizeof (ULONG) + c * sizeof (SWENTRY) ; 
p = (PSWBLOCK)malloc (cb); 
// £111 the array with SWENTRYs 
WinQuerySwitchList ( hab, p, cb ); 
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// display the fields of the SWENTRY for each entry 


tor ({ 


{ 


i = 0; 
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p->aswentry[i].swctl.bProgType ); 


Retrieves the size and position of the next window to be created. 


SYNTAX 


BOOL WinQueryTaskSizePos(HAB hab, ULONG zdSession, 
PSWP pswp) 


PARAMETERS 
hab - input 

Anchor block handle. 
id Session - input 


Pass the session identifier or zero for the current program’s session. 


pswp - output 


Pass the address of an SWP structure that this function fills in: 


typedef struct 


{ 
ULONG 
LONG 
LONG 
LONG 


EL? 
Cy; 


CX; 


vi 


_SWP 


/* swp */ 
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LONG xe 
HWND hwndIinsertBehind; 
HWND hwnd; 


ULONG ulReservedl1; 
ULONG ulReserved?; 
} SWP; 


fl A combination of SWP flags that you can use in a call to WinSet- 
WindowPos to size and position the window. See WinSetWindowPos 
for a description of the flags. 

cy The window's height in pixels. 

cx The window’s width in pixels. 

y The window's y-coordinate in pixels, relative to its parent’s lower 
left. 

x The window's x-coordinate in pixels, relative to its parent’s lower 
left. 

hwndInsertBehind The window's sibling immediately on top of it in 
the stack of windows. 

hwnd The window's handle. This field is used by the WinSetMult- 
WindowPos function, which uses this same structure. 

ulReservedl Reserved. 

ulReserved2 Reserved. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


OX1208 - PMERR_ INVALID PARAMETERS 
0OX120B - PMERR_INVALID_ SESSION_ID 


OTHER INFO 
Include file: pmshl.h Define: INCL_WINSWITCHLIST 


SEE ALSO 


WinSetWindowPos -311, WinStoreWindowPos -320, 
WinRestoreWindowPos -301, WinCreateStdWindow -17 


NOTES 


This function returns the size, position, and flags that the Worksplace 
Shell would assign to a standard window created with WinCreate- 
Std Window using the FCF_SHELLPOSITION flag. A program not using 
WinCreateStdWindow can use this function to size and position its 
main window. 
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@ WinQueryTaskTitle 


Retrieves a task list entry’s text string. 


SYNTAX 
ULONG WinQueryTaskTitle (ULONG zdSession, PSZ pszTiile, 
ULONG cb) 
PARAMETERS 


idSession - input 

Pass an OS/2 session identifier or 0 to specify the caller’s session. 
pszTitle - output 

Pass the address of a string that this function fills in. 

cb - input 

The string’s length. 


RETURNS 


Zero if successful, nonzero otherwise. 
Possible returns from WinGetLastError: 


0X1208 - PMERR_INVALID_PARAMETERS 
0X120B - PMERR_INVALID_SESSION_ID 


OTHER INFO 
Include file: pmshl.h Define: INCL_WINSWITCHLIST 


SEE ALSO 
WinQuerySessionTitle -409, WinQuerySwitchEntry -410 


NOTES 


This function is equivalent to WinQuerySessionTitle. 
This function is useful if you know a program’s session identifier, 
and require its task-list text. 





@ WinRemoveSwitchEntry 


Removes an entry from the task list. 
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SYNTAX 
ULONG WinRemoveSwitchEntry(HSWITCH hswitch) 


PARAMETERS 

hsuttch - input 

The task list handle returned by WinAddSwitchEntry, WinCreate- 
SwitchEntry, WinQuerySwitchList, or WinQuerySwitchEntry. 


RETURNS 
Zero if successful, nonzero otherwise. 


Possible returns from WinGetLastError: 


OX1202 - PMERR INVALID SWITCH_HANDLE 


OTHER INFO 
Include file: pmshl.h Define: INCL_WINSWITCHLIST 


SEE ALSO 


WinAddSwitchEntry -402, WinCreateSwitchEntry -404, 
WinQuerySwitchList -413, WinQuerySwitchEntry -407, 
WinCreateStdWindow -17 


NOTES 


You cannot remove entries for non-OS/2 programs because the system 
automatically removes them when the session expires. 

If you create a standard window with the FCF_TASKLIST flag, you 
don’t need to issue WinRemoveSwitchEntry to remove the text from 
the tasklist—when the frame window exits, it automatically removes 
the switch entry. 





WinStartApp 


Executes a program. 


SYNTAX 


HAPP WinStartApp(HWND hwndNotify, PPROGDETAILS pprogde, 
PSZ pszCmdLine, PVOID pReserved, ULONG /1) 
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PARAMETERS 

hwndNotify - input 

A window handle or NULLHANDLE. If you pass a window handle, the 
system passes that window the WM_APPTERMINATENOTIFY message 
when the program exits. 

pprogde - input 

Pass the address of a PROGDETAILS structure: 

typedef struct _PROGDETAILS /* progde */ 

{ 


ULONG Length; 
PROGTYPE Drogt: 

PSZ pszTitle; 

PSZ pszExecutable; 
PSZ pszParameters; 
PSZ pszStartupDir; 
PSZ Dezicon: 

PSZ pszEnvironment; 
SWP SwplInitial; 


} PROGDETAILS; 


Length ‘The size of the structure, in bytes. 
progt An embedded PROGTYPE structure: 


typedef struct _PROGTYPE /* progt */ 
{ 

PROGCATEGORY progc; 

ULONG fbVisible; 
} PROGTYPE; 


proge One of the following values: 

PROG 31 ENH Windows 3.l-enhanced mode—runs in Win- 
dow full-screen. 

PROG 31 ENHSEAMLESSCOMMON Windows 3.1-enhanced 
mode program that runs in a common Windows seamless ses- 
sion. 

PROG 31_ENHSEAMLESSVDM_ Windows 3.1-enhanced mode 
program that runs in its own Windows seamless session. 

PROG_31_STD Windows 3.1 standard mode program—runs 
in full-screen. 

PROG 31 STDSEAMLESSCOMMON Windows 3.1 standard 
mode program that runs in a common Windows seamless ses- 
sion. 
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PROG 31 STDSEAMLESSVDM_ Windows 3.1 standard mode 
program that runs in its own Windows seamless session. 
PROG DEFAULT PM determines type. 
PROG_FULLSCREEN  Full-screen OS/2 program. 
PROG _PM Presentation Manager program. 
PROG_VDM_ DOS program that runs in a full screen. 
PROG _WINDOWABLEVIO OS/2 windowable program. 
PROG _WINDOWEDVDM_ DOS program that runs in a window. 
PROG_WINDOW_REAL Windows real-mode program. 
fbVisible A combination of the following flags: 
SHE_VISIBLE 
SHE_INVISIBLE 
SHE_PROTECTED 
SHE_UNPROTECTED 
pszTitle The new program’s title, or pass NULL for EXE file name. 
pszExecutable The file name of the executable file. The system will 
search the list of directories specified by the PATH environment vari- 
able. 
pszParameters The parameters to pass to a new program or NULL. 
If you pass NULL, you can specify the arguments in the pszCmdLine 
argument. 
pszStartupDir ‘The startup current directory for the new program. 
Pass NULL to use the caller’s current directory. 
pszicon The file name of an icon that the system will attach to the 
new program. Pass NULL for no icon. 
pszEnvironment A set of environment strings, terminated with two 
bytes of zero. You can pass NULL to have the system assign the new 
process the same environment as the caller. 
swpInitial An embedded SWP structure that describes the new pro- 
gram ’s initial window size and position. See WinSetWindowPos for a 
description of this structure. 


pszCmdLine - input 

Pass the address of a string containing arguments for the new pro- 
gram, or NULL. If you pass a string, it should contain two back-to-back 
strings: the first should be the program’s file name; the second, the ar- 
guments, separated by spaces. 

pReserved - input 

Reserved—pass NULL. 


. 
Te | 
( gd &A) -——f SAF INSTALLEDCMDLINE Use the command line from system set- 


( 
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fl- input 
Any combination of the following flags, or zero for no flags: 
SAF BACKGROUND Start as a detached process. 


tings for this program. 

SAF MAXIMIZED = Start in a maximized window. 

SAF MINIMIZED Start in a minimized window. 

SAF STARTCHILDAPP Start as a child session—this allows the 
caller to terminate the new program with WinTerminateApp. 


RETURNS 


The new program’s application handle, or NULLHANDLE if an error 
occurred. 
Possible returns from WinGetLastError: 


OX1001 - PMERR INVALID HWND 

OX152f- PMERR_ INVALID _PROGRAM_CATEGORY 
0X1530 - PMERR_ INVALID_APPL 

OX1531 - PMERR CANNOT_START 


OTHER INFO 
Include file: pmshl.h Define: INCL_WINWINDOWMGR 


SEE ALSO 


WinTerminateApp -424, WinQueryTaskSizePos -416, 
WinSetWindowPos -311 


NOTES 


If you specify the SAF_STARTCHILDAPP option, you can stop the new 
program with WinTerminateApp. 

When the new program terminates, the system passes the notify 
window the WM_APPTERMINATENOTIPFY message. 


EXAMPLE 
‘This example starts a program and passes it an argument string: 
PROGDETAILS progde; 


HAPP happ; 
progde.Length = sizeof (PROGDETAILS) ; 
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progde.progt.progc = PROG_DEFAULT; 

progde.progt.fbVisible = SHE_VISIBLE; 

progde.pszTitle = NULL; 

progde.pszExecutable = “TEST.EXE’”; 

progde.pszParameters = NULL; 

progde.pszStartupDir = NULL; 

progde.psziIcon = NULL; 

progde.pszEnvironment = NULL; 

WinQueryTaskSizePos ( hab, 0, &progde.swpInitial ); 

happ = WinStartApp ( hwnd, &progde, “test.exe\Qargl arg2”, NULL, O ); 





WinSwitchToProgram 


Changes the active task. 


SYNTAX 
ULONG WinSwitchToProgram (HSWITCH hswitch) 


PARAMETERS 

hsunrtch - input 

The task list handle returned by WinAddSwitchEntry, WinCreate- 
SwitchEntry, WinQuerySwitchList, or WinQuerySwitchEntry. 


RETURNS 


Zero if successful, nonzero otherwise. 
Possible returns from WinGetLastError: 


0X1202 - PMERR_ INVALID _SWITCH_HANDLE 


OTHER INFO 
Include file: pmshl.h Define: INCL_WINSWITCHLIST 


SEE ALSO 


WinAddSwitchEntry -402, WinCreateSwitchEntry -404, 
WinQuerySwitchList -413, WinQuerySwitchEntry -410 
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NOTES 


This function only completes successfully if issued from the fore- 
ground session (the active window). In other words, the foreground 
session can make another session the foreground, but a nonfore- 
ground session cannot force itself to the foreground. 





@ WinTerminateApp 


Terminates a program started with WinStartApp. 


SYNTAX 
BOOL WinTerminateApp(HAPP happ) 


PARAMETERS 

happ - input 

An application handle returned by WinStartApp. 
RETURNS 


TRUE if succcessful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0X1533 - PMERR_ INVALID _HAPP 
0X1534 - PMERR_ CANNOT_STOP 


OTHER INFO 
Include file: pmshl.h Define: INCL_WINWINDOWMGR 


SEE ALSO 
WinStartApp -419 
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NOTES 

This function is effective only if SAF_STARTCHILDAPP was specified 

when the program was started. The notify window handle specified in 

WinStartApp will receive the WM_APPTERMINATENOTIFY message. 
You must call this function from the same process that called 


WinStartApp. 
This function requires the existence of a message queue on the 


calling thread. 


el) 
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oo in version 2.0, the OS/2 desktop is controlled by the Work- 
place Shell (WPS) program contained in PMSHELL.EXE. The 
Shell provides both an object-oriented user interface and an object- 
oriented programming interface. Each “icon” on the desktop is actu- 
ally an object residing in a dynamic link library, consisting of methods 
(functions) and data. These objects are defined by IBM’s System 
Object Model (SOM). Programmers can create their own object 
classes, and then register, create, and destroy instances of those objects 
using the functions described in this chapter. Writing the code for the 
object classes is not covered in this book, but the Workplace Shell 
methods are covered in a companion volume. 

In OS/2 2.0 and 2.1, nonobjects cannot call an object’s methods, 
because the OS/2 2.x version of SOM doesn’t support cross-process 
method calls. In OS/2 Warp 3 and above, SOM supports a technique 
called Distributed SOM (DSOM), which lets separate executable pro- 
grams call an object’s methods. 
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Workplace Shell Object Classes 


The Workplace Shell includes several prewritten, preregistered object 
classes from which developers can create instances. These include: 


Object Class Name __— Description Implementation 
WPDataFile Data files, e.g., TEST. TXT File 
WPProgramFile Executable file, e.g., TEST.EXE. File 


WPProgram Reference to executable Abstract; setting 
stored in OS2.INI 
WPFolder Contains other objects File directory; settings 


stored in OS2. INI 


Programs can create instances of these object classes using Win- 
CreateObject (pg 429). For example, an installation program for an 
application could copy the executable file to some directory on a hard 
disk, create a folder on the desktop, and insert a program object refer- 
ence in the folder. Then the user could start the application by double- 
clicking on the program object without needing to know where the ex- 
ecutable file resides. 


Setup Strings and Object IDs 


Most object classes recognize strings called setup strings that are con- 
ceptually similar to environment strings. Each object class defines its 
own setup strings, and inherits the setup strings from all of its ancestor 
classes. Programs can use the setup strings to configure the object. For 
example, a folder object recognizes a setup string BACKGROUND= 
TEST.BMP that assigns the folder’s background bitmap. You can assign 
the setup string when you create the object with WinCreateObject (pg 
429), or pass a setup string to an existing object with WinSetObjectData 
(pg 448). You can find documentation for the setup strings supported 
by the predefined object classes in the companion Workplace Shell 
Functions reference. 

When you create an object using WinCreateObject, you can assign 
to it a setup string called the olject ID, which has the form <xxxx> 
where you specify the xxxx. You can then use the object ID when you 
again call WinCreateObject to populate the folder. The Shell itself de- 
fines several object IDs for standard folders. 
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WinCopyObject copies an object into a folder (pg 428). 
WinCreateObject creates a new object in a folder (pg 429). 
WinCreateShadow creates a shadow of an object (pg 433). 
WinDeregisterObjectClass deregisters an object class (pg 433). 
WinDestroyObject destroys an object in a folder (pg 434). 
WinEnumObjectClasses enumerates the registered object classes (pg 
435). 

WinIsSOMDDReady determines if the DSOM daemon is started (pg 
437). 

WinIsWPDServerReady determines if the Workplace Shell DSOM 
server is ready (pg 438). 

WinLockupSystem locks the Workplace Shell (pg 439). 

WinMove Object moves an object from one folder to another (pg 439). 
WinOpenObject opens a view of an object or surfaces an existing view 
(pg 440). 

WinQueryActiveDesktopPathname returns the path name of the desk- 
top folder (pg 442). 

WinQueryObject returns an object handle, given an object ID string 
(pg 442). 

WinQueryObjectPath returns the path name of an object (pg 443). 
WinRegisterObjectClass registers an object class with the Workplace 
Shell (pg 444). 

WinReplaceObjectClass replaces an existing Workplace Shell class (pg 
445). 

WinRestartSOMDD starts the DSOM daemon running (pg 446). 
WinRestartWPDServer starts the Workplace Shell DSOM server run- 
ning (pg 447). 


- WinSave Object causes an object to save itself (pg 448). 


WinSetObjectData passes a setup string to an object (pg 448). 
WinShutdownSystem shuts down the Workplace Shell (pg 449). 
WinUnlockSystem unlocks the Workplace Shell (pg 450). 





WinCopyObject 


Copies an object into a folder. 
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SYNTAX 


BOOL WinCopyObject (HOBJECT holj, HOBJECT hobjFolder, 
ULONG ofiions) 


PARAMETERS 

hobj - input 

The handle of the object to copy. 

hobjFolder - input 

The handle of the folder in which to copy the object. 

options - input 

The only supported option is: 

CO_FAILIFEXISTS The function will fail with an error if an object 
with the given object ID or path name already exists. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0x1718 - WPERR_ALREADY EXISTS 
0x1719 - WPERR_INVALID_FLAGS 


OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 


SEE ALSO 


WinCreate Object -429, WinCreateShadow -433, WinQueryObject -442, 
WinMoveObject -439, WinSaveObject -448, WinOpen Object -440, 
WinSetObjectData -448 


NOTES 
This function is only valid in OS/2 3.0 and later. 





WinCreateObject 


Creates a new object in a folder. 
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SYNTAX 


HOBJECT WinCreateObject (PSZ pszClass, PSZ pszTitle, PSZ 
pszSetupString, PSZ pszLocation, 
ULONG options) 


PARAMETERS 

pszClass - input 

Pass a string naming a preregistered class or a class registered with 
WinRegisterObjectClass. 

pszTitle - input 

Pass a string that will act as the new object’s title. 

pszSetupString - input 

Pass a string that the Sheil will pass to the new object’s wpSetup method, 
or pass NULL for no setup string. The setup string consists of strings 
with the form: keyname=value. A keyname can have several values, sep- 
arated by commas; a setup string can have several keynames, each ter- 
minated with a semicolon. See the companion Workplace Shell Reference 
for a listing of the setup strings recognized by prewritten Shell object 
classes. Note that application-defined classes can define their own 
setup strings. To include a comma or colon in a setup string, precede 
the comma or semicolon with the caret (“) character. Note: if you in- 
clude an OBJECTID= in the setup string, it must be at the end of the 
setup string. 

pszLocation - input 

Pass a string that indicates in which folder to insert the new object. This 
string can be in one of two forms: 1. A string, called the object ID, with 
the form: <xxxx>. The Shell defines the following object ID strings: 


<LOCATION_DESKTOP> The desktop folder 
<WP_NOWHERE> The hidden folder 
<WP_OS2SYS> The OS/2 system folder 
<WP_TEMPS> The templates folder 
<WP_CONFIG> The system setup folder 
<WP_START> The startup folder 
<WP_INFO> The information folder 


<WP_DRIVES> The drives folder 
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Programs can assign their own object IDs to new objects by passing the 

setup string OBJECTID=<xxxx>; where xxxx is the new object’s string. 

2. A fully qualified path name of a directory. 

options - input 

One of the following values: 

CO_FAILIFEXISTS The function will fail with an error if an object 
with the given object ID or path name already exists. 

CO_REPLACEIFEXISTS The function will delete any existing ob- 
ject with the given object ID or path name. 

COQ_UPDATEIFEXISTS The function will pass the given setup string 
to any existing object with the given object ID or path name. 


RETURNS 


The object handle, or NULLHANDLE if an error occurred. 
Possible returns from WinGetLastError: 


0x1701 - WPERR_INVALID_ Ox1718 - WPERR_ALREADY_ 
CLASS EXISTS 

0x1720 - WPERR_INVALID_OBJECTID 

OTHER INFO 

Include file: pmwp.h Define INCL_WINWORKPLACE 

SEE ALSO 


WinDestroyObject -434, WinSetObjectData -448 


NOTES 


If you create an object descended from WPFileSystem (such as a WP- 
Folder), the object is created with an actual file and thus is persistent 
across system boots. If you create an object descended from WPAbstract 
(such as WPProgram), the object has no actual file, but is persistent 
since the Shell stores the object’s location in the OS2.INI file. If you cre- 
ate an object descended from WPTransient, the object is not persistent. 

After creating the object, a program can send it a setup string with 
WinSetObjectData. 

If you create a temporary object, be sure to delete it with Win- 
DestroyObject when you are finished with it. 
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EXAMPLE 


This example creates a folder on the desktop, assigning it an object ID. 


The program then creates a program object in the folder: 


#define INCL_WIN 

#include <os2.h> 

#include <stdio.h> 

#include <string.h> 

int main (int argc, char *argv[ ] ) 


{ 


HAB hab; // anchor block 

BOOL fSuccess; // return from API 
HOBJECT hobj; // program object handle 
HOBJECT hobjFolder; // folder object handle 


hab = WinInitialize (0 ); 
// create a folder called “Test” 
hobjFolder = WinCreateObject (“WPFolder” 
, “Test” 
, "“OBJECTID=<MY FOLDER>” 
, “WP _ DESKTOP>* 
, CO_REPLACEIFEXISTS ); 
1£ (hobjFolder == NULLHANDLE ) 
{ 
printf (“Unable to create folder, error: ” ); 
printf (”%x\n”, ERRORIDERROR (WinGetLastError (hab 
return 1; 
} 
// create a program object in the folder 
hobj = WinCreateObject (“WPProgram” 
; “Tesc* 
, “EXENAME=C: \\TEST\\TEST. EXE” 
, “<MY_FOLDER>” 
, CO_REPLACEIFEXISTS ); 
if (hobj == NULLHANDLE ) 
{ 


printf (“Unable to create program object, error: ” ); 


printf (”“%x\n”, ERRORIDERROR (WinGetLastError (hab ) 
return 1; 

} 

WinTerminate (hab ); 


return 0; 


} }3 
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@ WinCreateShadow 





Creates a shadow of an object. 


SYNTAX 

HOBJECT WinCreateShadow (HOBJECT hobj, HOBJECT hobjFolder, 
ULONG reserved) 

PARAMETERS 

hobj - input 


The handle of the object to shadow. 

hobjFolder - input 

The handle of the folder in which to shadow the object. 
reserved - input 

Not currently used—pass zero. 


RETURNS 
The shadow object’s handle, or NULLHANDLE if an error occurred. 
Possible returns from WinGetLastError: 


0x1718 - WPERR_ALREADY EXISTS 
0x1719 - WPERR_INVALID_FLAGS 


OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 


SEE ALSO 


WinCreateObject -429, WinCopyObject -428, WinQueryObject -442, 
WinMoveObject -439, WinSaveObject -448, WinOpenObject -440, 
WinSetObjectData -448 


NOTES 


This function is only valid in OS/2 3.0 and later. 
A shadow object is different from a copy, because actions (except 
for delete) on the shadow affect the original object. 





@ WinDeregisterObjectClass 


Deregisters an object class. 
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SYNTAX 
BOOL WinDeregisterObjectClass (PSZ pszClass) 


PARAMETERS 
pszClass - input 
Pass a string naming a class registered with WinRegisterObjectClass. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0X170F - WPERR_NOT_WORKPLACE_CLASS 


OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 


SEE ALSO 
WinRegisterObjectClass -444, WinReplaceObjectClass -445 


NOTES 


When a class is registered, the Shell writes an entry into OS2.INI indi- 
cating the class’s name and the dynamic link library in which it resides. 
WinDeregisterObjectClass removes this entry from OS2.INI. 





@ WinDestroyObject 


Destroys an object in a folder. 


SYNTAX 
BOOL WinDestroyObject (HOBJECT hot) 


PARAMETERS 
hobj - input 
The handle of the object to destroy. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0X1714 - WPERR_OBJECT_NOT_FOUND 
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OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 


SEE ALSO 
WinCreateObject -428, WinQueryObject -442 


NOTES 


This function permanently deletes the object referenced by hobj and 
removes any entries for that object from OS2.INI. 





WinEnumObjectClasses 


Enumerates the registered object classes. 


SYNTAX 

BOOL WinEnumObjectClasses (POBJCLASS podjcls, PULONG 
pulSize) 

PARAMETERS 


pobjels - output 

Pass a pointer to memory in which the system will return a linked list 
containing an entry for each object class registered. Each entry in the 
list is a structure: 


typedef struct _OBJCLASS #* oOcis. */ 


{ 
struct _OBJCLASS *pNext; 


PSZ pszClassName; 
PSZ pszModName; 
} OBJCLASS; 


pNext Pointer to the next entry in the list. This pointer will be NULL 
in the last entry. 

pszClassName ‘The class name string. 

pszModName The name of the dynamic link library containing the 
object class. 


pulSize - input/output 
Pass the address of a ULONG containing the size, in bytes, of the mem- 
ory pointed to by podjcls. If the ULONG contains zero, this function 
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does not copy any data to the buffer, but returns the required size of 
the buffer in the ULONG. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0X1705 - WPERR_BUFFER_TOO_SMALL 


OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 


SEE ALSO 
WinRegisterObjectClass -444, WinDeregisterObjectClass -433 


EXAMPLE 


This program displays all registered object classes on the console: 


#define INCL WIN 
#include <os2.h> 
#include <stdio.h> 


#include <stdlib.h> 


int main (int argc, char *argv[] ) 


{ 


HAB hab; // anchor block 

BOOL fSuccess; // return from API 
POBJCLASS p; // object class data 
POBJCLASS pTemp; // temp pointer 
ULONG cy: // size of buffer 


hab = WinInitialize (0 ); 


// determine size of buffer required and allocate storage 
eb = O; 
£fSuccess = WinEnumObjectClasses (NULL, &cb ); 
p = (POBJCLASS)malloc (cb); 


// £111 the buffer 


fSuccess = WinEnumObjectClasses (p, &cb ); 
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// traverse the linked list, displaying each entry 


pTemp = p; 
if (pTemp != NULL ) 
do 
{ 
printf (“Name = %s\n”, pTemp->pszClassName ); 


printf (“DLL = %s\n”, pTemp->pszModName ); 
prance fhe 
premp = pTemp->pNext ; 

} while (pTemp->pNext != NULL ); 


// clean up 
free (p ); 
WinTerminate (hab ); 


return 0; 


Ww 





@ WinlsSOMDDReady 


Determines if the DSOM daemon is started. 


SYNTAX 
BOOL WinIsSOMDDReady (void) 


PARAMETERS 


None 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 


SEE ALSO 


WinRestartsSOMDD -446, WinIsWPDServerReady -438, 
WinRestartWPDServer -447 


NOTES 


This function is only available in OS/2 version 3.0 and later. 
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In OS/2 version 3.0 and later, the Workplace Shell allows an exe- 
cutable program to call methods in objects running in the Shell 
process. The Shell uses the Distributed SOM (DSOM) framework from 
the System Object Model (SOM) to allow cross-process method calls. 
DSOM requires that a background, or daemon process, be running 
before any cross-process method calls are attempted. This function de- 
termines if the daemon has been started with WinRestartSOMDD. 

You can also determine if the daemon process is running with the 
WPDSINIT-EXE command line program. 





WinlsWPDServerReady 


Determines if the Workplace Shell DSOM server is ready. 


SYNTAX 
BOOL WinIsWPDServerReady (void) 


PARAMETERS 


None 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 


SEE ALSO 
WinRestartWPDServer -447, WinIsSSOMDDReady -437 


NOTES 


This function is only available in OS/2 version 3.0 and later. 

In OS/2 3.0 and later, the Workplace Shell allows an executable 
program to call methods in objects running in the Shell process. The 
Shell uses the Distributed SOM (DSOM) framework from the System 
Object Model (SOM) to allow cross-process method calls. DSOM re- 
quires that a server process be running before any cross-process 
method calls are attempted. This function determines if the Shell’s 
server process has been started with WinRestartWPDServer. 
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You can also determine if the Shell server’s process is running 
with the WPDSINIT.EXE command-line program. 





WinLockupSystem 


Locks the Workplace Shell. 


SYNTAX 
BOOL WinLockupSystem (HAB hab) 


PARAMETERS 
hab - input 
Anchor block handle. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinUnlockSystem -450, WinSetHook -57 


NOTES 


This function is only available in OS/2 2.1 and later. 

This function locks the Workplace Shell. ‘To unlock, you must call 
WinUnlockSystem from a background thread, as this function doesn’t 
return until the WinUnlockSystem is called successfully. 

Typically, a program displays a dialog with an entry field where the 
user enters a password. The program then calls WinUnlockSystem with 
the password to unlock the Workplace Shell. The window that displays 
the lockup message should have the WS_CLIPSIBLINGS style. 

If there are any LockupHook functions installed, the system calls 
them during this function. 





WinMoveObject 


Moves an object from one folder to another. 
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SYNTAX 


BOOL WinMoveObject (HOBJECT hodj, HOBJECT hobjFolder, 
ULONG options) 


PARAMETERS 

hobj - input 

The handle of the object to move. 

hobjFolder - input 

The handle of the folder in which to move the object. 

options - input 

The only supported option is: 

CO_FAILIFEXISTS The function will fail with an error if an object 
with the given object ID or path name already exists. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0X1718 - WPERR_ALREADY EXISTS 
0X1719 - WPERR_INVALID_FLAGS 


OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 


SEE ALSO 


WinCreateObject -429 WinQueryObject -442, WinCopyObject -428, 
WinSave Object -448, WinOpen Object -440, WinSetObjectData -448 


NOTES 


This function is only valid in OS/2 version 3.0 and later. 





@ WinOpenObject 
Opens a view of an object or surfaces an existing view. 


SYNTAX 
BOOL WinOpenObject (HOBJECT hobj, ULONG wulView, BOOL ff) 
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PARAMETERS 

hobj - input 

The handle of the object to open. 

ulView - input 

Specifies which view to open. Any object class can define its own pri- 
vate view codes, but the system defines the following: 


OPEN _CONTENTS Open contents view. 

OPEN_DEFAULT Open the default view for the object. 

OPEN_DETAILS Open a folder’s details view. 

OPEN_HELP Open help. 

OPEN_RUNNING Start the EXE referenced by a program object 
running. 

OPEN_SETTINGS Open the settings notebook. 

OPEN_TREE Open a folder’s tree view. 

f- input 

Pass either ‘TRUE or FALSE: 


TRUE The Shell first determines if a view of the given type is already 
open. If not, the Shell calls the object’s wpOpen method to open a view. 
If a view is already open, the Shell examines the object’s concurrent 
view setting (the user can set this in the object’s Window page in the 
Settings notebook: “Object Open Behavior”). If the concurrent view 
setting says “Display existing window,” the Shell surfaces the existing 
view. If the concurrent view setting says “Create new window,” the Shell 
calls the object’s wpOpen method to open a view. 

FALSE The Shell ignores the object’s concurrent view setting and al- 
ways calls the object’s wpOpen method to open a view. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0X1714 - WPERR_OBJECT_NOT_FOUND 
0X1719 - WPERR_INVALID_FLAGS 


OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 
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SEE ALSO 
WinCreate Object -429 


NOTES 


This function is only available in OS/2 version 3.0 and later. 





@ WinQueryActiveDesktopPathname 


Returns the path name of the desktop folder. 


SYNTAX 
BOOL WinQueryActiveDesktopPathname (PSZ pszPath, ULONG cb) 


PARAMETERS 

pszPath - output 

Pass the address of a memory buffer to which this function writes the 
desktop folder’s path name. 

cb - input 

Pass the length of the memory buffer, in bytes. 

RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0X1705 - WPERR_BUFFER_TOO_SMALL 


OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 


SEE ALSO 
WinQueryObjectPath -443 


NOTES 


This function is only available in OS/2 version 3.0 and later. 





@ WinQueryObject 


Returns an object handle, given an object ID string . 
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SYNTAX 
HOBJECT WinQueryObject (PSZ pszObjectID) 


PARAMETERS 

pszObjectLD - input 

The object ID string assigned to the object by WinCreateObject or 
WinSetObjectData, or the fully qualified path name of the object. 


RETURNS 


The object handle, or NULLHANDLE if an error occurred. 
Possible returns from WinGetLastError: 


0X1714 - WPERR_OBJECT_ 0X1720 - WPERR_INVALID_ 
NOT_FOUND OBJECTID 

OTHER INFO 

Include file: pmwp.h Define: INCL_WINWORKPLACE 

SEE ALSO 


WinCreateObject -429, WinSetObjectData -448, WinDestroyObject - 
434, WinCopyObject -428, WinMoveObject -439, WinOpenObject - 
440, WinSaveObject -448 





WinQueryObjectPath 


Returns the path name of an object. 


SYNTAX 

BOOL WinQueryObjectPath (HOBJECT holj, PSZ pszPath, 
ULONG 0) 

PARAMETERS 

hobj - input 


The handle of the object to query. 

pszPath - output 

Pass the address of a memory buffer to which this function writes the 
object’s path name. 

cb - input 

Pass the length of the memory buffer, in bytes. 
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RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


OX1645 - PMERR INVALID PARAMETER 
0X1705 - WPERR_BUFFER_TOO_SMALL 
0X1714 - WPERR_OBJECT_NOT_FOUND 


OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 


SEE ALSO 
WinCreateObject -429, WinQueryObject -442 


NOTES 


This function is only available in OS/2 version 3.0 and later. If you at- 
tempt to query the path name of a nonfile object (such as a WPProgram 
object), this function fails and WinGetLastError returns PMERR_IN- 
VALID_PARAMETER. 





@ WinRegisterObjectClass 


Registers an object class with the Workplace Shell. 


SYNTAX 
BOOL WinRegisterObjectClass (PSZ pszClass, PSZ pszMod) 


PARAMETERS 

pszClass - input 

The name of the object class to register. Application-defined classes 
should not use the characters WP as a prefix on class names. 

pszMod - input 

The fully qualified path name of the dynamic link library containing 
the object class. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0X1701 - WPERR_INVALID_CLASS 
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OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 


SEE ALSO 
WinDeregisterObjectClass -433, WinReplaceObjectClass -445 


NOTES 


The DLL must contain a class or classes that were created using the 
System Object Model. If the object class overrides the wphclsQuery- 
Instancelype or wpclsQuerylnstancefilier methods, the Shell calls those 
methods during this function. 





WinReplaceObjectClass 


Replaces an existing Workplace Shell class. 


SYNTAX 

BOOL WinReplaceObjectClass (PSZ pszOngClass, PSZ pszReplace, 
BOOL f) 

PARAMETERS 


pszOrigClass - input 

Pass a string containing the name of an object class registered by 
WinRegisterObjectClass. 

pszReplace - input 

Pass a string containing the name of an object class registered by 
WinRegisterObjectClass that will replace pszOngClass. 

f-input 

Pass TRUE to replace the original class, FALSE to revert back to the 
original. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0X1701 - WPERR_INVALID_CLASS 
0X1702 - WPERR_INVALID_SUPERCLASS 
OX170C - WPERR_INVALID_OLDCLASS 
0X170D - WPERR_INVALID_NEWCLASS 
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OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 


SEE ALSO 
WinRegisterObjectClass -444 


NOTES 


The replacement class must be a descendant of the original class. 





@ WinRestartSOMDD 





Starts the DSOM daemon running. 


SYNTAX 
ULONG WinkRestartSOMDD (BOOL f) 


PARAMETERS 

f- input 

Pass TRUE to start the daemon, FALSE to stop it. 
RETURNS 


0 if successful, non-zero otherwise. 


OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 


SEE ALSO 
WinIsSOMDDReady -437, WinRestartWPDServer -447 


NOTES 


This function is only available in OS/2 version 3.0 and later. 

In OS/2 version 3.0 and later, the Workplace Shell allows an exe- 
cutable program to call methods in objects running in the Shell 
process. The Shell uses the Distributed SOM (DSOM) framework from 
the System Object Model (SOM) to allow cross-process method calls. 
DSOM requires that a background, or daemon process, be running be- 
fore any cross-process method calls are attempted. 


Workplace Shell Functions 447 


You can also start the daemon process running with the WPDS 
INIT.EXE command line program and by adding the following line to 
the CONFIG.SYS file: 


WPDSERVERSTART=ON 





WinRestartWPDServer 





Starts the Workplace Shell DSOM server running. 


SYNTAX 
ULONG WinRestartWPDServer (BOOL /) 


PARAMETERS 


f- input 
Pass TRUE to start the Workplace Shell server process, FALSE to stop it. 


RETURNS 


0 if successful, non-zero otherwise. 


OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 


SEE ALSO 
WinIsWPDServerReady -438, WinRestartSOMDD -446 


NOTES 


This function is only available in OS/2 version 3.0 and later. 

In OS/2 version 3.0 and later, the Workplace Shell allows an exe- 
cutable program to call methods in objects running in the Shell 
process. The Shell uses the Distributed SOM (DSOM) framework from 
the System Object Model (SOM) to allow cross-process method calls. 
DSOM requires that a server process be running before any cross- 
process method calls are attempted. 

You can also start the server process running with the WPDS- 
INIT.EXE command line program and by adding the following line to 
the CONFIG.SYS file: 


WPDSERVERSTART=ON 
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@ WinSaveObject 


Causes an object to save itself. 


SYNTAX 
BOOL WinSaveObject (HOBJECT hodj, BOOL fAsync) 


PARAMETERS 
hobj - input 
The handle of the object to save. 


fAsyne - input 
Pass TRUE to have the object save itself on a background thread, 
FALSE to have it save itself immediately. 


RETURNS 
TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0X1714 -WPERR_OBJECT_NOT_FOUND 
0X1719 - WPERR_INVALID_FLAGS 


OTHER INFO 
Include file: pmwp.h Define: INCL_WINWORKPLACE 


SEE ALSO 


WinCreate Object -429, WinQueryObject -442, 
WinQueryObjectPath -443, WinOpenObject -440 


NOTES 


This function is only available in OS/2 version 3.0 and later. ‘This func- 
tion calls the wpSaveState method on the object, informing the object 
that it should save its state to persistent storage. 





@ WinSetObjectData 


Passes a setup string to an object. 
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SYNTAX 
BOOL WinSetObjectData (HOBJECT hodj, PSZ pszSetupString) 


PARAMETERS 

hobj - input 

The handle of the object to which to pass the setup string. 
pszSetupString - input 

Pass a string that the Shell will pass to the object’s wpSetup method. The 
setup string consists of strings with the form: keyname=value. A key- 
name can have several values, separated by commas; a setup string can 
have several keynames, each terminated with a semicolon. See the 
companion Workplace Shell Reference for a listing of the setup strings 
recognized by prewritten Shell object classes. Note that application- 
defined classes can define their own setup strings. To include a comma 
or colon in a setup string, precede the comma or semicolon with the 
caret (‘) character. Note: if you include an OBJECTID= in the setup 
string, it must be at the end of the setup string. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


0X1714 - WPERR_OBJECT_NOT_FOUND 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINWORKPLACE 


SEE ALSO 
WinCreateObject -429, WinQueryObject -442 





WinShutdownSystem 


Shuts the Workplace Shell down. 


SYNTAX 
BOOL WinShutdownSystem (HAB hab, HMQ hmq) 
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PARAMETERS 

hab - input 

Anchor block handle. 
hmg - input 

Message queue handle. 


RETURNS 

TRUE if successful, FALSE otherwise. 

OTHER INFO 

Include file: pmwp.h Define: INCL_WINWORKPLACE 
NOTES 


This function sends WM_SAVEAPPLICATION and WM_QUIT messages 
to PM programs and then calls DosShutdown. 





® WinUnlockSystem 


Unlocks the Workplace Shell. 


SYNTAX 
BOOL WinUnlockSystem (HAB hab, PSZ pszPassword) 


PARAMETERS 

hab - input 

Anchor block handle. 

pszPassword - input 

A string containing a password. This function compares the password 
string with the system password, stored by the system in encrypted form. 
The user can set the password in the Settings notebook for the Desktop. 


RETURNS 
TRUE if successful, FALSE otherwise. 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINMESSAGEMGR 


SEE ALSO 
WinUnlockSystem -450, WinSetHook -57 
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NOTES 


This function is only available in OS/2 2.1 and later. 

This function unlocks the Workplace Shell. To unlock, you must 
call WinUnlockSystem from a thread other than the one that locked 
the shell, as WinLockSystem doesn’t return until the user successfully 
enters a password. 

Typically, a program displays a dialog with an entry field where the 
user enters a password. The program then calls WinUnlockSystem with 
the password to unlock the Workplace Shell. The window that displays 
the lockup message should have the WS_CLIPSIBLINGS style. 

If there are any LockupHook functions installed, the system calls 
them during this function. 





Nationa 
Language Support 
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Pesce page is a set of character, images, or glyphs. The character 
value or code point, acts as an index into the code page. For ex- 
ample, in the Multinational code page (number 850), the character 
value 65 (0x41) corresponds to uppercase A. Many code pages are ef- 
fectively supersets of the ASCII table in this regard. However, many na- 
tional languages contain characters that are not in the standard ASCII 
table, but do exist in the code page for that national language. For ex- 
ample, the German lowercase 0 with an umlaut (0) has code point of 
148 in code page 850. 

In addition, many Asian languages, for example Chinese, need 
more than the 256 characters provided in a single-byte code page, the 
Multinational code page. Such languages require a double-byte char- 
acter set, where each character occupies 16 bits rather than 8. 

The standard library shipped with most C compilers contains 
functions to convert characters to uppercase, count characters in a 
string, and so on. Unfortunately, these functions do not work properly 
with code points above 128. 
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To help programs deal with national language support, 
Presentation Manager provides functions to switch code pages, trans- 
late characters between code pages, convert characters to uppercase, 
and traverse double-byte character set strings. The default code page 
and an alternate code page for the system are defined in the CON- 
FIG.SYS file in the CODEPAGE= statement. The keyboard, display, and 
printer all use this default code page. Users can switch between the de- 
fault and alternate code pages using the OS/2 CHCP.EXE utility pro- 
gram. A program can set the code page for its input with WinSetCp 
(pg 462) and for its output with GpiSetCp. 


Code Pages 


Here is a list of some of the available code pages: 


Country Code Page Value Remarks 

Canadian-French 863 

Desktop Publishing 1004 Microsoft Windows-compatible 

Iceland 861 

Latin 1 Multilingual 850 

Latin 2 Multilingual 852 

Nordic 865 

Portuguese 860 

Turkey 857 

U.S: 437 Contains IBM PC character graphics 
characters 


Country Codes 


In addition to code pages, OS/2 also defines country codes, which 
specify currency format and so forth. Here is a list of some of the avail- 
able country codes: 
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Country 
Arabic 
Australian 
Belgian 
Canadian-French 
Danish 

Finnish 

French 
German 
Hebrew 

Italian 
Japanese 
Korean 
Latin-American 
Netherlands 
Norwegian 
Portuguese 
Simpl. Chinese 
Spanish 
Swedish 

Swiss 

Trad. Chinese 
UK-English 
US-English 


Unspecified 
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Code 

785 
61 
32 


45 
358 
Bo 
49 
972 
39 
Sl 
82 


ob 
47 
351 
86 
34 
46 
4] 
88 
44 
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NLS Functions 





WinCompareStrings determines if two character strings are the same 
(pg 455). 

WinCpTranslateChar translates a character from one code page to an- 
other (pg 456). 

WinCpTranslateString translates a character string from one code 
page to another (pg 457). 

WinNextChar traverses forward in a character string (pg 458). 
WinPrevChar traverses backward in a character string (pg 460). 
WinQueryCp retrieves the current code page number (pg 461). 
WinQueryCpList retrieves a list of code pages (pg 461). 

WinSetCp sets the code page for a queue (pg 462). 

WinUpper converts a string to uppercase (pg 463). 

WinUpperChar converts a character to uppercase (pg 464). 





© WinCompareStrings 


Determines if two character strings are the same. 


SYNTAX 


ULONG WinCompareStrings (HAB hab, ULONG idCodePage, 
ULONG idCounitry, PSZ psz1, PSZ psz2, 
ULONG wilReserved) 


PARAMETERS 

hab - input 

Anchor block handle. 

id CodePage - input 

Code page for both strings, or pass zero to use the current code page. 
idCountry - input 

Country code for both strings, or pass zero to use the current country 
code. 

psz1 - input 

Pass the address of the first string. 

psz2 - input. 

Pass the address of the second string. 
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ulReserved - input. 
Not currently used—pass zero. 


RETURNS 

One of the following values: 

0-WCS_ ERROR An error occurred. 

1 - WCS_EQ Strings are equal. 

2-WCS_LT String one is less than string two. 
3-WCS_GT String one is greater than string two. 


Possible returns from WinGetLastError: 


OX100B - PMERR_INVALID_STRING_PARM 
OX101D - PMERR_INVALID_SRC_CODEPAGE 
OXIOIE - PMERR INVALID_DST_CODEPAGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCOUNTRY 


SEE ALSO 
WinUpper -463, WinCpTranslateString -457 


NOTES 


See the beginning of the chapter for a list of code pages and country 
codes. 





@ WinCpTranslateChar 


Translates a character from one code page to another. 


SYNTAX 


UCHAR WinCpTranslateChar (HAB hab, ULONG idCPSrc, UCHAR 
ucSrc, ULONG idCPDst) 


PARAMETERS 
hab - input 
Anchor block handle. 
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wdCPSrc - input 

The source code page. 

ucSre - input 

The character value (code point) to translate. 
1dCPDst - input 

The destination code page. 


RETURNS 


The character value (code point) in the destination code page, or 255 
if the character doesn’t exist in the destination code page, or zero if 
the call failed. 


Possible returns from WinGetLastError: 
OX101D -PMERR INVALID SRC CODEPAGE 
OX1O1LE-PMERR INVALID DST CODEPAGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCOUNTRY 


SEE ALSO 
WinCpTranslateString -457 


NOTES 


You cannot use this function to translate to or from a double-byte code 
page, since it accepts and returns an 8-bit value. You can use WinCp- 
TranslateString instead. See the beginning of the chapter for a list of 
code pages. 





WinCp TranslateString 


Translates a character string from one code page to another. 


SYNTAX 


BOOL WinCpTranslateString (HAB hab, ULONG idCPSvrc, PSZ pszSre, 
ULONG 7dCPDst, ULONG cbDest, PSZ 
pszDest) 


PARAMETERS 
hab - input 
Anchor block handle. 
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wdCPSrc - input 

The source code page. 

pszSrc - input 

The source string. 

1dCPDst - input 

The destination code page. 

cbDest - input 

The length of the output buffer in bytes. 
pszDest - output 

Pass the address of a memory buffer to which this function writes the 
translated string. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


OX101D - PMERR_INVALID_SRC_CODEPAGE 
OXIOLE - PMERR_ INVALID_DST_CODEPAGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCOUNTRY 


SEE ALSO 
WinCpTranslateChar -456 


NOTES 


This function translates all of the characters in the input string, stop- 
ping when it finds the null terminator. The output string must be large 
enough to hold the translation; since this function can translate from 
a single-byte code page to a double-byte code page, the output buffer 
may need to be larger than the input string. 

If this function cannot translate a source character because the 
destination code page doesn’t contain the character, the function 
writes the value 255 to the output character position. This is not con- 
sidered an error. 

See the beginning of the chapter for a list of code pages. 





@ WinNextChar 





Traverses forward in a character string. 
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SYNTAX 
PSZ WinNextChar (HAB hab, ULONG idCP ULONG idCouniry, 
PSZ pszCurrent) 
PARAMETERS 
hab - input 
Anchor block handle. 
1d CP - input 
The input string’s code page, or pass zero to use the current code 
page. 


idCountry - input 

Not currently used—set to zero. 
pszCurrent - input 

Pass the address of a string. 


RETURNS 


A pointer to the next character in the string, or NULL if the call failed. 
Possible returns from WinGetLastError: 


OX100B - PMERR_INVALID STRING_PARM 
0X101D - PMERR_INVALID_SRC_CODEPAGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCOUNTRY 


SEE ALSO 
WinPrevChar -460 


NOTES 


Programs typically call this function in a loop to traverse through the 
string’s characters. ‘This function returns a pointer to the next charac- 
ter, which may not be the next byte if the string is defined in a multi- 
ple-byte character set code page. 

When the string end is reached, the output pointer will point to 
the null terminator in the input string. 

See the beginning of the chapter for a list of code pages and coun- 
try codes. 
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@ WinPrevChar 





Traverses backward in a character string. 


SYNTAX 


PSZ WinPrevChar (HAB hab, ULONG idCR ULONG idCountry, PSZ 
pszStart, PSZ pszCurrent) 


PARAMETERS 

hab - input 

Anchor block handle. 

1dCP - input 

The input string’s code page, or pass zero to use the current code 
page. 

tdCountry - input 

Not currently used—set to zero. 

pszStart - input 

Pass the address of the beginning of the input string. 
pszCurrent - input 

Pass the address of a character in a string. 


RETURNS 


A pointer to the previous character in the string, or NULL if the call 
failed. 
Possible returns from WinGetLastError: 


OX100B - PMERR_ INVALID _STRING_PARM 
OX101D - PMERR_ INVALID _SRC_CODEPAGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCOUNTRY 


SEE ALSO 
WinNextChar -458 


NOTES 


Programs typically call this function in a loop to traverse through the 
string’s characters. This function returns a pointer to the next charac- 
ter, which may not be the next byte if the string is defined in a multi- 
ple-byte character set code page. 
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When the string start is reached, the output pointer will point to 
the input string. 

See the beginning of the chapter for a list of code pages and coun- 
try codes. 





WinQueryCp 
Retrieves the current code page number. 


SYNTAX 
ULONG WinQueryCp (HMQ hig) 


PARAMETERS 

hmg - input 

Message queue handle, or pass HMQ_CURRENT for the current mes- 
sag queue handle. 


RETURNS 


The current code page number, or zero if an error occurred. 
Possible returns from WinGetLastError: 


OX1002 - PMERR_INVALID_ HMQ 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCOUNTRY 


SEE ALSO 


WinQueryCpList -461, WinSetCp -462, WinCpTranslateChar -456, 
WinCpTranslateString -457 





WinQueryCpList 
Retrieves a list of code pages. 


SYNTAX 


ULONG WinQueryCpList (HAB hab, ULONG count, PULONG 
pulCodePages) 
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PARAMETERS 

hab - input 

Anchor block handle. 

count - input 

The number of code page values to return. 

pulCodePages - output 

Pass the address of an array of ULONGs to which this function writes 
the code page list. 


RETURNS 


The number of code pages, or zero if an error occurred. 
Possible returns from WinGetLastError: 


0X1003 - PMERR_PARAMETER_OUT_OF RANGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCOUNTRY 


SEE ALSO 
WinQueryCp -461, WinSetCp -462 


NOTES 


This function returns an array of code page values. A program can call 
this function twice: the first time passing zero for the count so that the 
function returns the number of code page values. The program can 
then allocate memory for the array and call the function again. 





@ WinSetCp 


Sets the code page for a queue. 


SYNTAX 
BOOL WinSetCp (HMQ hing, ULONG idcp) 


PARAMETERS 

hmgq - input 

Message queue handle, or pass HMQ_CURRENT for the current mes- 
sage queue. 
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idcp - input 
Code page value. This must be one of the two values specified in the 
CODEPAGE statement in CONFIG.SYS. 


RETURNS 


TRUE if successful, FALSE otherwise. 
Possible returns from WinGetLastError: 


OX1002 - PMERR_ INVALID _HMQO 
0OX101D - PMERR_INVALID_SRC_CODEPAGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCOUNTRY 


SEE ALSO 
WinQueryCp -461 


NOTES 
See the beginning of the chapter for a list of code pages. 





WinUpper 


Converts a string to uppercase. 


SYNTAX 


ULONG WinUpper (HAB hab, ULONG 7dCP ULONG :dCountry, 
PSZ pszSrc) 


PARAMETERS 

hab - input 

Anchor block handle. 

idCP - input 

The input string’s code page, or pass zero to use the current code 
page. 

1dCountry - input 

The character’s country code, or pass zero to use the default. 

pszSre - input 

Pass the address of the string to be converted. 
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RETURNS 


The number of characters converted, or zero if an error occurred. 
Possible returns from WinGetLastError: 


OX100B - PMERR_INVALID_STRING_PARM 
OX101D - PMERR_INVALID_SRC_CODEPAGE 
OXIOLE - PMERR INVALID _DST_CODEPAGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCOUNTRY 


SEE ALSO 
Win UpperChar -464, WinNextChar -458, WinPrevChar -460 


NOTES 


See the beginning of the chapter for a list of code pages and country 
codes. 





@ WinUpperChar 


Converts a character to uppercase. 


SYNTAX 


ULONG WinUpperChar (HAB hab, ULONG idCR ULONG 
zdCountry, ULONG ulChar) 


PARAMETERS 

hab - input 

Anchor block handle. 

1dCP - input 

The input character’s code page, or pass zero to use the current code 
page. 

idCountry - input 

The character’s country code, or pass zero to use the default. 

ulChar - input 

The character to convert. 


National Language Support 465 


RETURNS 


The converted character, or zero if an error occurred. 
Possible returns from WinGetLastError: 


OX101D - PMERR_INVALID_SRC_CODEPAGE 
OXIOLE - PMERR_INVALID_DST_CODEPAGE 


OTHER INFO 
Include file: pmwin.h Define: INCL_WINCOUNTRY 


SEE ALSO 
WinUpper -463, WinNextChar -458, WinPrevChar -460 


NOTES 


See the beginning of the chapter for a list of code pages and country 
codes. 








@ WinLockVisRegions 


Prevents output to all visible regions on the desktop. 


SYNTAX: 
BOOLWinLockVisRegions (HWND hwndDesktop, BOOL fLock) 


PARAMETERS: 


hwndDesktop - input 

The desktop window handle. 

fLock - input 

Pass TRUE to lock, FALSE to unlock. 


RETURNS: 


TRUE if successful, FALSE if otherwise. 
Possible returns from WinGetLastError: 
0X1001 - PMERR_ INVALID HWND 


OTHER INFO: 
Include file: pmwin.h Define: INCL_WINWINDOWMGR 


SEE ALSO: 
WinLockWindowUpdate - 142 


NOTES: 


This function prevents output to all windows on the desktop. PM main- 
tains a lock count—if the same thread locks the desktop more than 
once, it must unlock an equal number of times before the lock is re- 
leased. 

While the desktop is locked, you should not send any messages 
nor call an functions that send messages. 
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WinAddAtom 359 
WinAddSwitchEntry 402 
WinAlarm Sl 
WinAssociateHelpInstance 261 
WinBeginEnum Windows 274 
WinBeginPaint 105 
WinBroadcastMsg 35 
WinCalcFrameRect is 
WinCallMseFilter 36 
WinCancelShutdown 2 
WinChangeswitchEntry 404 
WinCheckButton 168 
WinCheckInput al 
WinCheckMenultem 153 
WinCloseClipbrd 370 
WinCompareStrings 455 
WinCopyAccelTable 228 
WinCopyObject 428 
WinCopyRect 389 
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WinCpTranslateChar 
WinCpTranslateString 
WinCreateAccelTable 
WinCreateAtomTable 
WinCreateCursor 
WinCreateDlg 
WinCreateFrameControls 
WinCreateHelpInstance 
WinCreateHelpTable 
WinCreateMenu 
WinCreateMsgQueue 
WinCreateObject 
WinCreatePointer 
WinCreatePointerIndirect 
WinCreateShadow 
WinCreateStd Window 
WinCreateSwitchEntry 
WinCreateWindow 
WinDdelInitiate 
WinDdePostMsg 
WinDdeRespond 
WinDefDlgProc 
WinDefFileDlgProc 
WinDefFontDlgProc 
WinDefWindowProc 
WinDeleteAtom 
WinDeleteLboxItem 
WinDeleteLibrary 
WinDeleteProcedure 
WinDeregisterObjectClass 
WinDestroyAccelTable 
WinDestroyAtomTable 
WinDestroyCursor 

Win DestroyHelpInstance 
WinDestroyMsgQueue 
WinDestroyObject 
WinDestroyPointer 
WinDestroyWindow 
WinDismissDlg 
WinDispatchMsg 
WinDIgBox 
WinDrawBitmap 
WinDrawBorder 
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WinDrawPointer 12] 
WinDrawText 12? 
WinEmptyClipbrd 377 
WinEnableControl 176 
WinEnableMenultem 157 
WinEnablePhysInput 84 
WinEnableWindow 85 
WinEnableWindowUpdate 86 
WinEndEnumWindows 274 
WinEndPaint 106 
WinEnumClipbrdFmts 378 
WinEnumDlgItem 177 
WinEnumObjectClasses 435 
WinEqualRect 390 
WinExcludeUpdateRegion 137 
WinFileDlg 210 
WinFillRect 125 
WinFindAtom 362 
WinFlashWindow 87 
WinFocusChange 88 
WinFontDlg 215 
WinFreeErrorInfo 10 
WinFreeFileDlgList ae0 
WinFreeFileIcon 238 
WinGetClipPS 107 
WinGetCurrentTime 326 
WinGetDlgMsg 178 
WinGetErrorInfo 6 
WinGetKeyState 89 
WinGetLastError 9 
WinGetMaxPosition 275 
WinGetMinPosition 2T7 
WinGetMsg oo 
WinGetNextWindow 278 
WinGetPS 108 
WinGetPhysKeyState 91 
WinGetScreenPS 109 
WinGetSysBitmap 327 
WinInSendMsg 42 
WinInflateRect 39] 
Winlnitialize 10 
WinInsertLboxItem 179 


WinIntersectRect 392 


WinInvalidateRect 
WinInvalidateRegion 
WinInvertRect 
WinIsChild 
WinIsControlEnabled 
WinIsMenultemChecked 
WinIsMenultemEnabled 
WinIsMenultem Valid 
WinIsPhysInputEnabled 
WinIsRectEmpty 
WinIsSOMDDReady 
WinIsThreadActive 
WinIsWPDServerReady 
WinIsWindow 
WinIsWindowEnabled 
WinIsWindowShowing 
WinIsWindowVisible 
WinLoadAccelTable 
WinLoadDlg 
WinLoadFileIcon 
WinLoadHelpTable 
WinLoadLibrary 
WinLoadMenu 
WinLoadMessage 
WinLoadPointer 
WinLoadProcedure 
WinLoadString 
WinLockPointerUpdate 
WinLockVisRegions 
WinLockWindowUpdate 
WinLockupSystem 
WinLockupSystem 
WinMakePoints 
WinMakeRect 
WinMapDlgPoints 
WinMapWindowPoints 
WinMessageBox 
WinMessageBox2 
WinMoveObject 
WinMultWindowFfromIDs 
WinNextChar 
WinNextChar 
WinOffsetRect 
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WinOpenClipbrd 378 
WinOpenObject 440 
WinOpenWindowDCG 110 
WinPeekMsg 43 
WinPopupMenu 161 
WinPostMsg 44 
WinPostQueueMsg 45 
WinPrevChar 460 
WinProcessDlg 190 
WinPtinRect 395 
WinQueryAccelTable 247 
WinQueryActiveDesktopPathname 442 
WinQueryActiveWindow 94 
WinQueryAnchorBlock 11 
WinQueryAtomLength 363 
WinQueryAtomName 365 
WinQueryAtom Usage 366 
WinQueryButtonCheckState 192 
WinQueryCapture 94 
WinQueryClassInfo 26 
WinQueryClassName 27 
WinQueryClassThunkProc 46 
WinQueryClipbrdData 379 
WinQueryClipbrdFmtInfo 381 
WinQueryClipbrdOwner 382 
WinQueryClipbrdViewer 382 
WinQueryCp 461 
WinQueryCpList 461 
WinQueryCursorInfo 95 
WinQueryDesktopBkgnd aaa 
WinQueryDesktopWindow 331 
WinQueryDlgItemShort 192 
WinQueryDlgItemText 194 
WinQueryDlgItemTextLength 195 
WinQueryFocus 96 
WinQueryHelpInstance 268 
WinQueryLboxCount 196 
WinQueryLboxItemText 196 
WinQueryLboxItemTextLength 197 
WinQueryLboxSelectedItem 198 
WinQueryMsgPos 47 
WinQueryMsgTime 48 
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WinQueryObjectPath 
WinQueryObjectWindow 
WinQueryPointer 
WinQueryPointerInfo 
WinQueryPointerPos 
WinQueryPresParam 
WinQueryQueuelnfo 
WinQueryQueueStatus 
WinQuerysession Title 
WinQueryswitchEntry 
WinQueryswitchHandle 
WinQuerysSwitchList 
WinQuerysysColor 
WinQuerysSysModalWindow 
WinQuerysysPointer 
WinQuerysysPointerData 
WinQuerysysValue 
WinQuerysystemAtom Table 
WinQueryTaskSizePos 
WinQueryTaskTitle 
WinQueryUpdateRect 
WinQueryUpdateRegion 
WinQueryVersion 
WinQueryVisibleRegion 
WinQueryWindow 
WinQueryWindowDC 
WinQueryWindowModel 
WinQueryWindowPos 
WinQueryWindowProcess 
WinQueryWindowPtr 
WinQueryWindowRect 
WinQueryWindow [ext 
WinQueryWindowlextLength 
WinQueryWindowThunkProc 
WinQueryWindowULong 
WinQueryWindowUShort 
WinRealizePalette 
WinRegisterClass 
WinRegisterObjectClass 
WinReleaseHook 
WinReleasePS 
WinRemovePresParam 
WinRemoveSwitchEntry 
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WinReplaceObjectClass 445 
WinRequestMutexSem 53 
WinRestartSOMDD 446 
WinRestartSOMDD 447 
WinRestartWPDServer 447 
WinRestoreWindowPos 301 
WinSaveObject 448 
WinSave WindowPos 302 
WinScrollWindow 129 
WinSendDlgItemMsg i392 
WinSendMsg 54 
WinSetAccelable 25] 
WinSetActiveWindow 97 
WinSetCapture 98 
WinSetClassMsgInterest 55 
WinSetClassThunkProc 56 
WinSetClipbrdData 383 
WinSetClipbrdOwner 385 
WinSetClipbrdViewer 386 
WinSetCp 462 
WinSetDesktopBkgend 348 
WinSetDlgItemShort | 200 
WinSetDlgItemText 201 
WinSetFileIcon 253 
WinSetFocus ! 99 
WinSetHook 57 
WinSetKeyboardState Table 100 
WinSetLboxItemText 202 
WinSetMenultemText 164 
WinSetMsgInterest 69 
WinSetMsgMode 70 
WinSetMultWindowPos 303 
WinSetObjectData 448 
WinSetOwner 305 
WinSetParent 306 
WinSetPointer 254 
WinSetPointerOwner 255 
WinSetPointerPos 256 
WinSetPresParam 307 
WinSetRect 396 
WinSetRectEmpty a97 
WinSetSynchroMode 70 
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WinSetSysModalWindow 
WinSetSysPointerData 
WinSetSysValue 
WinSetVisibleRegionNotity 
WinSetWindowBbits 
WinSetWindowPos 
WinSetWindowPtr 
WinSetWindow [ext 
WinSetWindowTLhunkProc 
WinSetWindowULong 
WinSetWindowUShort 
WinShowCursor 
WinShowPointer 
WinShow IrackRect 
WinShowWindow 
WinShutdownSystem 
WinStartApp 
WinStart Timer 
WinStopTimer 
WinStoreWindowPos 
WinSubclassWindow 
WinSubstituteStrings 
WinSubtractRect 
WinSwitchToProgram 
Win Terminate 
WinTerminateApp 
Win TrackRect 
WinTranslateAccel 
WinUnionRect 
WinUnlockSystem 
Win UpdateWindow 
Win Upper 
WinUpperChar 
WinValidateRect 
WinValidateRegion 
WinWaitEventSem 
Win WaitMsg 
WinWaitMuxWaitSem 
WinWindowFromDC 
WinWindowFromID 
WinWindowFromPoint 
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A 


Accelerators, definition of, 226 
ACCEL structure, 229 
ACCELTABLE structure, 228, 230 
Active window, 79, 94, 98 

Anchor block, 10 

Atoms, 357 


B 
Bitmap (s): 

fonts, 223 

definition of, 2265 

drawing of, 115 

system, 327 
Border, drawing of, 118 
BM_QUERYCHECK message, 192 
BM_SETCHECK message, 169 


Cc 


Cached micro PS, 104, 106, 107, 108, 109 
Capturing the mouse, 98 
CheckMsgFilter hook procedure, 60 
Child window, 279, 289, 306 
CLASSINFO structure, 26 
Class styles, 29 
Cleanup functions, 2 
Client window, 14, 15 
Clipboard: 
delayed rendering, 26 
formats, 369 | 
Code examples: 
error information, 7 
file dialog, 224 
message resource, 242 
popup menu, 163 
presentation params, 287 
standard window, 21 
string resource, 246 
system colors, 335 
tracking rectangle, 134 
WinDrawBitmap, 117 


WinDrawText, 124 
WinGetKeyState, 90 
WinGetMsg, 42 
Win MessageBox2, 190 
WinOpwnWindowDG, 111 
WM_PAINT, 106 
Code page, 61, 453 
CodePageChanged hook procedure, 61 
Colors: 
RGB, 309 
system, 333 
CONVCONTEXT structure, 372, 376 
Coordinates, dialog, 167, 183 
Country codes, 453 
Creating a menu, 151 
Cursor, text entry, 78, 82 
CURSORINFO structure, 95 


D 


DDESTRUCT structure, 374 

Delayed rendering, clipboard, 381, 384 

DESKTOP structure, 330, 348 

Desktop window, 274, 331 

DestroyWindow hook procedure, 61 

Device context, 103 

Dialog coordinates, 167, 183 

Dialog, modal, 166, 172, 174, 175, 179, 181, 186, 
190 

Dialog, modeless, 166, 172, 174, 181 

Distributed SOM (DSOM), 426 

DLGITEM structure, 170 

DLGTEMPLATE structure, 1770 

DSOM daemon, 437 

DSOM server, 438 


E 


Error codes, 9 

Error processing, 2 
ERRORIDERROR macro, 9 
ERRORIDSEV macro, 9 
ERRORINEFO structure, 6 
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F 


FATTRS structure, 223 
File dialog standard controls, 205 
FILEDLG structure, 210 
FindWord hook procedure, 61 
FlushBuf hook procedure, 62 
Focus change sequence, 79 
Focus window, 78, 98 
Folders, Workplace Shell, 430 
Font dialog standard controls, 205 
FONTDLG structure, 216 
Fonts: 

bitmap, 223 

outline, 223 
FRAMECDATA structure, 16, 25 
Frame creation flags, 18 
Frame window, 14, 15, 88, 94, 262, 272, 298, 299, 

315, 317, 318 


H 


Help hook, 62 

HELPINIT structure, 262 

Help table hierarchy, 266 

HELPTABLE structure, 265 
HM_ERROR message, 268 
HM_LOAD_HELP_TABLE message, 268 


I 


Icon, definition of, 226 

Icon extended attribute, 240 
ICONINFO structure, 253, 341, 355 
Information Presentation Facility, 260 
Input hook procedure, 63 

Integer atom, 357 

Invalid rectangle, 142 

Invalid region, 136 


J 


JournalPlayback hook procedure, 64 
JournalRecord hook procedure, 64 


L 


LM_DELETEITEM message, 173 
LM_INSERTITEM message, 180 
LM_QUERYITEM message, 199 
LM_QUERYITEMCOUNT message, 196 
LM_QUERYITEMTEXT message, 197, 199 
LM_QUERYITEMTEXTLENGTH message, 198 


LM_SETITEMTEXT message, 203 
Loader hook procedure, 64 
Lockup hook procedure, 65 


M 


MAKEFIXED macro, 218 
MB2D structure, 189 
MB2INFO structure, 187 
Menu: 

creating, 151 

item attributes, 153 

item styles, 152 

window styles, 151 
Message control hook, 55 
Message filter hook, 36 
Message filtering, 41, 76 
Message input hook, 37 
Message processing, order of, 32, 41 
Message queue, 4 
Message resource, 226 
Messages, posted, 33 
Messages, sent, 33 
Micro presentation space, 104 
MM_ISITEMVALID message, 160 
MM_QUERYITEMATTR message, 158 
MM_SETITEMATTR message, 153, 154, 157 
MM_SETITEMTEXT message, 165 
Mnemonic character, 315 
Modal dialog, 166, 172, 174, 175, 179, 181, 186, 

190 

Modal loop, 67, 133, 174, 191 
Modal window, 337, 352 
Modeless dialog, 166, 172, 174 
Mouse capture, 98 
MOQINFO structure, 49 
MsgControl hook procedure, 66 
MsgFilter hook procedure, 67 
MsgInput hook procedure, 68 
MT structure, 155 
MTT structure, 155 
Mutex semaphore, 53 


N 


Normal presentation space, 104 


O 


OBJCLASS structure, 435 
Object IDs, Workplace Shell, 427, 430 


Object window, 274, 332 
OS2.INI profile, 29, 321, 325 
OS2SYS.INI profile, 325 
Outline fonts, 223 
OWNERITEM structure, 219 
Owner window, 289, 305 


P 


Palette, 127 
Parent window, 289, 306 
Pointer(s): 

definition of, 226 

drawing of, 121 

system, 337 
POINTERINFO structure, 233, 249 
Posted message, 33 
Presentation parameter, 271, 307 
Presentation space, 103 
Process identifier, 292 
Profiles, 325 
PROGDETAILS structure, 420 
PROGTYPE structure, 420 
Public window class, 27, 29, 31 


Q 

OMSG structure, 36, 38, 40, 59, 178, 258 
Queue, system, 59 

Queue, thread, 59 

QWL_USER field, 271 


R 


Rectangle, invalid, 142 
RECTL structure, 388 
Region, invalid, 136 
Region, visible, 135 
RGB colors, 309, 350 


S 


Semaphore, event, 74 

Semaphore, mutex, 53 
Semaphore, mux wait, 76 
SendMsg hook procedure, 69 

Sent messages, 33, 42, 54, 68 

Setup functions, 2 

Setup strings, Workplace Shell, 427 
Sibling windows, 22 

SMHSTRUCT structure, 68, 69 
Standard window, 14, 17, 417 
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Standard window component windows, 21 
String, definition of, 226 
Styles: 
class, 29 
window, 22 
SWBLOCK structure, 413 
SWCNTRL structure, 402, 405, 407, 410, 413 
SWENTRY structure, 413 
SWP structure, 275, 277, 291, 302, 303, 416 
Synchronous paint windows, 147 
System event queue, 59 
System Object Model (SOM), 426 
System values, 342 


T 


Task list, 401 
Text entry cursor, 78 
Text, drawing of, 122 
Thread: 
background, 3, 11 
identifier, 292 
message queue, 59 
Thunk procedure, 57, 72 
TRACKINFO structure, 131 


V 


View codes, wpOpen, 441 
Virtual key codes, 80, 101 
Visible region, 135 


W 
Window: 

active, 79 

desktop, 274, 331 

focus, 79 

modal, 337, 352 

object, 274, 332 
Window class name, 13 
Window class, public, 27 
Window data structure, 30, 270 
Window extra bytes, 30, 270 
Window styles, 22 
Window words, 270 
WM_ACTIVATE message, 79, 313 
WM_ADJUSTFRAMEPOS message, 302 
WM_ADJUSTWINDOWPOS message, 25, 313 
WM_CALCFRAMERECT message, 15 
WM_CALCVALIDRECTS message, 313 
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WM_CHAR message, 41, 78, 259 

WM_CLOSE message, 173 

WM_COMMAND message, 41, 150, 152, 161, 174, 
211, 215, 218, 229, 231, 248, 252, 258 

WM_CREATE message, 25, 166 

WM_DDE_INITIATEACK message, 373 

WM_DDE_INITIATE message, 372 

WM_DESTRYCLIPBOARD message, 378, 385 

WM_DESTROY message, 26 

WM_DRAWCLIPBOARD message, 371 

WM_DRAWITEM message, 152, 161 

WM_DRAWITEM message, font dialog, 219 

WM_ENABLE message, 86 

WM_FLASHWINDOW message, 88 

WM_FOCUSCHANGE message, 79 

WM_HELP message, 41, 150, 161, 211, 218, 229, 
231, 258 

WM_HELP message, file dialog, 211 

WM_HITTEST message, 29 

WM_INITDLG message, 166, 171, 175, 182, 208, 
209 

WM_INITMENU message, 150, 152, 161, 381 

WM_MEASUREITEM message, 152, 161 

WM_MOUSEMOVE message, 255 

WM_MOVE message, 29, 313 

WM_MSGBOXDISMISS message, 188, 189 

WM_NULL message, 259 

WM_PAINT message, dialogs, 173, 184 

WM_PAINT message, 19, 22, 29, 41, 105, 106, 107, 
135, 136, 139, 140, 146, 147, 148, 149, 287, 
310 

WM_PRESPARAMCHANGED message, 271, 287, 
301, 310 


WM_QUERYFOCUSCHAIN message, 79 

WM_QUERYWINDOWPARAMS message, 193, 
194, 195, 295, 296 

WM_QUIT message, 2, 41, 179, 450 

WM_REALIZEPALETTE message, 128 

WM_RENDERFMT message, 381, 384 

WM_SAVEAPPLICATION message, 450 

WM_SEM1 message, 41 

WM_SEM2 message, 41 

WM_SEMS3 message, 41 

WM_SETFOCUS message, 78, 79, 83, 84 

WM_SETSELECTION message, 79, 201, 202, 315 

WM_SHOW message, 87, 313, 320 

WM_SIZE message, 313 

WM_SUBSTITUTESTRING message, 203 

WM_SYSCOLORCHANGE message, 335, 352 

WM_SYSCOMMAND message, 41, 150, 152, 161, 
229, 231, 258 

WM_SYSVALUECHANGED message, 271, 356 

WM_TIMER message, 41, 73 

WM_UPDATEFRAME message, 156, 161 

WM_VNRDISABLED message, 142, 146 

WM_VNRENABLED message, 142, 146 

Workplace Shell Object Classes, 427 

wpOpen method, 441 

wpSaveState method, 448 

wpsSetup method, 449 
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Z 
Z-order, 24, 279 
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